feat: add events & raw pipeline barriers to graphics ext (v1.5.0)

hoffstadt-nasa · hoffstadt-nasa · commit 5d531e74b467 · 2025-09-09T08:34:50.000-05:00
diff --git a/docs/version.txt b/docs/version.txt
@@ -60,7 +60,7 @@ the API is complete. It just means we won't break what currently exists.
 * Draw Backend        v1.0.1 (pl_draw_backend_ext.h)
 * DXT                 v1.0.0 (pl_dxt_ext.h)
 * GPU Allocators      v1.0.0 (pl_gpu_allocators_ext.h)
-* Graphics            v1.4.1 (pl_graphics_ext.h)
+* Graphics            v1.5.0 (pl_graphics_ext.h)
 * Image               v1.0.0 (pl_image_ext.h)
 * Job                 v2.0.0 (pl_job_ext.h)
 * Atomics             v1.0.0 (pl_platform_ext.h)
diff --git a/extensions/pl_graphics_cpu.c b/extensions/pl_graphics_cpu.c
@@ -164,6 +164,12 @@ typedef struct _plTimelineSemaphore
     plTimelineSemaphore* ptNext; // for linked list
 } plTimelineSemaphore;
 
+typedef struct _plTimelineEvent
+{
+    plDevice* ptDevice; // for convience
+    plTimelineEvent* ptNext; // for linked list
+} plTimelineEvent;
+
 typedef struct _plFrameContext
 {
     // VkSemaphore    tRenderFinish;
@@ -188,6 +194,9 @@ typedef struct _plDevice
     // timeline semaphore free list
     plTimelineSemaphore* ptSemaphoreFreeList;
 
+    // timeline evene free list
+    plTimelineEvent* ptEventFreeList;
+
     // render pass layout generation pool
     plCpuRenderPassLayout* sbtRenderPassLayoutsHot;
     plRenderPassLayout*    sbtRenderPassLayoutsCold;
@@ -326,6 +335,35 @@ pl_get_semaphore_value(plDevice* ptDevice, plTimelineSemaphore* ptSemaphore)
     return ulValue;
 }
 
+plTimelineEvent*
+pl_create_event(plDevice* ptDevice)
+{
+    plTimelineEvent* ptEvent = pl__get_new_event(ptDevice);
+    return ptEvent;
+}
+
+void
+pl_cleanup_event(plTimelineEvent* ptEvent)
+{
+    pl__return_event(ptEvent->ptDevice, ptEvent);
+}
+
+void
+pl_reset_event(plCommandBuffer* ptCmdBuffer, plTimelineEvent* ptEvent, plPipelineStageFlags tSrcStages)
+{
+}
+
+void
+pl_set_event(plCommandBuffer* ptCmdBuffer, plTimelineEvent* ptEvent, plPipelineStageFlags tFlags)
+{
+}
+
+void
+pl_wait_for_events(plCommandBuffer* ptCmdBuffer, plTimelineEvent** atEvents, uint32_t uEventCount, plPipelineStageFlags tSrcStages, plPipelineStageFlags tDstStages)
+{
+}
+
+
 plBufferHandle
 pl_create_buffer(plDevice* ptDevice, const plBufferDesc* ptDesc, plBuffer **ptBufferOut)
 {
@@ -700,6 +738,11 @@ pl_cleanup_device(plDevice* ptDevice)
     pl__cleanup_common_device(ptDevice);
 }
 
+void
+pl_pipeline_barrier(plCommandBuffer* ptCommandBuffer, plPipelineStageFlags beforeStages, plAccessFlags beforeAccesses, plPipelineStageFlags afterStages, plAccessFlags afterAccesses)
+{
+}
+
 void
 pl_pipeline_barrier_blit(plBlitEncoder* ptEncoder, plShaderStageFlags beforeStages, plAccessFlags beforeAccesses, plShaderStageFlags afterStages, plAccessFlags afterAccesses)
 {
diff --git a/extensions/pl_graphics_ext.c b/extensions/pl_graphics_ext.c
@@ -968,6 +968,24 @@ pl__get_new_semaphore(plDevice* ptDevice)
     return ptSemaphore;
 }
 
+static plTimelineEvent*
+pl__get_new_event(plDevice* ptDevice)
+{
+    plTimelineEvent* ptEvent = ptDevice->ptEventFreeList;
+    if(ptEvent)
+    {
+        ptDevice->ptEventFreeList = ptEvent->ptNext;
+    }
+    else
+    {
+        ptEvent = PL_ALLOC(sizeof(plTimelineEvent));
+        memset(ptEvent, 0, sizeof(plTimelineEvent));
+    }
+    ptEvent->ptDevice = ptDevice;
+    ptEvent->ptNext = NULL;
+    return ptEvent;
+}
+
 static void
 pl__return_render_encoder(plRenderEncoder* ptEncoder)
 {
@@ -996,6 +1014,13 @@ pl__return_semaphore(plDevice* ptDevice, plTimelineSemaphore* ptSemaphore)
     ptDevice->ptSemaphoreFreeList = ptSemaphore;
 }
 
+static void
+pl__return_event(plDevice* ptDevice, plTimelineEvent* ptEvent)
+{
+    ptEvent->ptNext = ptDevice->ptEventFreeList;
+    ptDevice->ptEventFreeList = ptEvent;
+}
+
 static plRenderPassHandle
 pl_get_encoder_render_pass(plRenderEncoder* ptEncoder)
 {
@@ -1240,6 +1265,7 @@ pl_load_graphics_ext(plApiRegistryI* ptApiRegistry, bool bReload)
         .create_bind_group_pool                 = pl_create_bind_group_pool,
         .cleanup_bind_group_pool                = pl_cleanup_bind_group_pool,
         .reset_bind_group_pool                  = pl_reset_bind_group_pool,
+        .pipeline_barrier                       = pl_pipeline_barrier,
         .pipeline_barrier_blit                  = pl_pipeline_barrier_blit,
         .pipeline_barrier_render                = pl_pipeline_barrier_render,
         .pipeline_barrier_compute               = pl_pipeline_barrier_compute,
@@ -1266,6 +1292,11 @@ pl_load_graphics_ext(plApiRegistryI* ptApiRegistry, bool bReload)
         .push_compute_debug_group               = pl_push_compute_debug_group,
         .pop_compute_debug_group                = pl_pop_compute_debug_group,
         .insert_debug_label                     = pl_insert_debug_label,
+        .create_event                           = pl_create_event,
+        .cleanup_event                          = pl_cleanup_event,
+        .reset_event                            = pl_reset_event,
+        .set_event                              = pl_set_event,
+        .wait_for_events                        = pl_wait_for_events,
 
         #if defined(PL_GRAPHICS_EXPOSE_VULKAN) && defined(PL_VULKAN_BACKEND)
         .get_vulkan_instance        = pl_get_vulkan_instance,
diff --git a/extensions/pl_graphics_ext.h b/extensions/pl_graphics_ext.h
@@ -114,7 +114,7 @@ Index of this file:
 // [SECTION] apis
 //-----------------------------------------------------------------------------
 
-#define plGraphicsI_version {1, 4, 1}
+#define plGraphicsI_version {1, 5, 0}
 
 //-----------------------------------------------------------------------------
 // [SECTION] includes
@@ -149,6 +149,7 @@ typedef struct _plSampler           plSampler;           // sampler resource
 typedef struct _plTexture           plTexture;           // texture resource
 typedef struct _plBuffer            plBuffer;            // buffer resource
 typedef struct _plTimelineSemaphore plTimelineSemaphore; // timeline semaphore
+typedef struct _plTimelineEvent     plTimelineEvent;     // timeline event
 
 // swapchains
 typedef struct _plSwapchain     plSwapchain;     // swapchain
@@ -360,6 +361,13 @@ typedef struct _plGraphicsI
     void             (*end_command_recording)  (plCommandBuffer*);
     void             (*submit_command_buffer)  (plCommandBuffer*, const plSubmitInfo*);
 
+    // timeline events
+    plTimelineEvent* (*create_event)   (plDevice*);
+    void             (*cleanup_event)  (plTimelineEvent*);
+    void             (*reset_event)    (plCommandBuffer*, plTimelineEvent*, plPipelineStageFlags srcStages);
+    void             (*set_event)      (plCommandBuffer*, plTimelineEvent*, plPipelineStageFlags srcStages);
+    void             (*wait_for_events)(plCommandBuffer*, plTimelineEvent**, uint32_t eventCount, plPipelineStageFlags srcStages, plPipelineStageFlags dstStages);
+
     // render encoder
     plRenderEncoder*   (*begin_render_pass)         (plCommandBuffer*, plRenderPassHandle, const plPassResources*); // do not store
     void               (*next_subpass)              (plRenderEncoder*, const plPassResources*);
@@ -409,9 +417,10 @@ typedef struct _plGraphicsI
     plCommandBuffer* (*get_blit_encoder_command_buffer)(plBlitEncoder*);
 
     // global barriers
-    void (*pipeline_barrier_blit)   (plBlitEncoder*,    plPipelineStageFlags beforeStages, plAccessFlags beforeAccesses, plPipelineStageFlags afterStages, plAccessFlags afterAccesses);
-    void (*pipeline_barrier_compute)(plComputeEncoder*, plPipelineStageFlags beforeStages, plAccessFlags beforeAccesses, plPipelineStageFlags afterStages, plAccessFlags afterAccesses);
-    void (*pipeline_barrier_render) (plRenderEncoder*,  plPipelineStageFlags beforeStages, plAccessFlags beforeAccesses, plPipelineStageFlags afterStages, plAccessFlags afterAccesses);
+    void (*pipeline_barrier)        (plCommandBuffer*,  plPipelineStageFlags beforeStages, plAccessFlags beforeAccesses, plPipelineStageFlags afterStages, plAccessFlags afterAccesses);
+    void (*pipeline_barrier_blit)   (plBlitEncoder*,    plPipelineStageFlags beforeStages, plAccessFlags beforeAccesses, plPipelineStageFlags afterStages, plAccessFlags afterAccesses); // memory barrier only in Metal backend
+    void (*pipeline_barrier_compute)(plComputeEncoder*, plPipelineStageFlags beforeStages, plAccessFlags beforeAccesses, plPipelineStageFlags afterStages, plAccessFlags afterAccesses); // memory barrier only in Metal backend
+    void (*pipeline_barrier_render) (plRenderEncoder*,  plPipelineStageFlags beforeStages, plAccessFlags beforeAccesses, plPipelineStageFlags afterStages, plAccessFlags afterAccesses); // memory barrier only in Metal backend
 
     //-----------------------------------------------------------------------------
 
diff --git a/extensions/pl_graphics_internal.h b/extensions/pl_graphics_internal.h
@@ -95,11 +95,13 @@ static plRenderEncoder*         pl__get_new_render_encoder(void);
 static plComputeEncoder*        pl__get_new_compute_encoder(void);
 static plBlitEncoder*           pl__get_new_blit_encoder(void);
 static plTimelineSemaphore*     pl__get_new_semaphore(plDevice*);
+static plTimelineEvent*         pl__get_new_event(plDevice*);
 
 static void pl__return_render_encoder(plRenderEncoder*);
 static void pl__return_compute_encoder(plComputeEncoder*);
 static void pl__return_blit_encoder(plBlitEncoder*);
 static void pl__return_semaphore(plDevice*, plTimelineSemaphore*);
+static void pl__return_event(plDevice*, plTimelineEvent*);
 
 // deletion
 static plFrameGarbage* pl__get_frame_garbage(plDevice*);
diff --git a/extensions/pl_graphics_metal.m b/extensions/pl_graphics_metal.m
@@ -36,6 +36,8 @@
     plBeginCommandInfo   tBeginInfo;
     plDevice*            ptDevice;
     id<MTLCommandBuffer> tCmdBuffer;
+    id<MTLEvent>         tEvent;
+    uint64_t             uEventValue;
     plCommandBuffer*     ptNext;
 } plCommandBuffer;
 
@@ -141,6 +143,14 @@
     plTimelineSemaphore* ptNext;
 } plTimelineSemaphore;
 
+typedef struct _plTimelineEvent
+{
+    plDevice* ptDevice; // for convience
+    id<MTLEvent> tEvent;
+    plTimelineEvent* ptNext; // for linked list
+    uint64_t uValue;
+} plTimelineEvent;
+
 typedef struct _plMetalBindGroup
 {
     id<MTLBuffer>         tShaderArgumentBuffer;
@@ -208,6 +218,9 @@
 
     plTimelineSemaphore* ptSemaphoreFreeList;
 
+    // timeline evene free list
+    plTimelineEvent* ptEventFreeList;
+
     // render pass layouts
     plMetalRenderPassLayout* sbtRenderPassLayoutsHot;
     plRenderPassLayout*      sbtRenderPassLayoutsCold;
@@ -738,6 +751,41 @@
     return 0;
 }
 
+plTimelineEvent*
+pl_create_event(plDevice* ptDevice)
+{
+    plTimelineEvent* ptEvent = pl__get_new_event(ptDevice);
+    ptEvent->tEvent = [ptDevice->tDevice newEvent];
+    return ptEvent;
+}
+
+void
+pl_cleanup_event(plTimelineEvent* ptEvent)
+{
+    pl__return_event(ptEvent->ptDevice, ptEvent);
+}
+
+void
+pl_reset_event(plCommandBuffer* ptCmdBuffer, plTimelineEvent* ptEvent, plPipelineStageFlags tSrcStages)
+{
+    ptEvent->uValue++;
+}
+
+void
+pl_set_event(plCommandBuffer* ptCmdBuffer, plTimelineEvent* ptEvent, plPipelineStageFlags tFlags)
+{
+    [ptCmdBuffer->tCmdBuffer encodeSignalEvent:ptEvent->tEvent value:ptEvent->uValue];
+}
+
+void
+pl_wait_for_events(plCommandBuffer* ptCmdBuffer, plTimelineEvent** atEvents, uint32_t uEventCount, plPipelineStageFlags tSrcStages, plPipelineStageFlags tDstStages)
+{
+    for(uint32_t i = 0; i < uEventCount; i++)
+    {
+        [ptCmdBuffer->tCmdBuffer encodeWaitForEvent:atEvents[i]->tEvent value:atEvents[i]->uValue];
+    }
+}
+
 static plBufferHandle
 pl_create_buffer(plDevice* ptDevice, const plBufferDesc* ptDesc, plBuffer** ptBufferOut)
 {
@@ -1876,6 +1924,7 @@
     while(ptCurrentCommandBuffer)
     {
         plCommandBuffer* ptNextCommandBuffer = ptCurrentCommandBuffer->ptNext;
+        ptCurrentCommandBuffer->tEvent = nil;
         PL_FREE(ptCurrentCommandBuffer);
         ptCurrentCommandBuffer = ptNextCommandBuffer;
     }
@@ -2254,9 +2303,20 @@
 }
 
 void
-pl_pipeline_barrier_blit(plBlitEncoder* ptEncoder, plPipelineStageFlags beforeStages, plAccessFlags beforeAccesses, plPipelineStageFlags afterStages, plAccessFlags afterAccesses)
+pl_pipeline_barrier(plCommandBuffer* ptCommandBuffer, plPipelineStageFlags beforeStages, plAccessFlags beforeAccesses, plPipelineStageFlags afterStages, plAccessFlags afterAccesses)
 {
+    if(ptCommandBuffer->tEvent == nil)
+    {
+        ptCommandBuffer->tEvent = [ptCommandBuffer->ptDevice->tDevice newEvent];
+    }
+
+    [ptCommandBuffer->tCmdBuffer encodeSignalEvent:ptCommandBuffer->tEvent value:++ptCommandBuffer->uEventValue];
+    [ptCommandBuffer->tCmdBuffer encodeWaitForEvent:ptCommandBuffer->tEvent value:ptCommandBuffer->uEventValue];
+}
 
+void
+pl_pipeline_barrier_blit(plBlitEncoder* ptEncoder, plPipelineStageFlags beforeStages, plAccessFlags beforeAccesses, plPipelineStageFlags afterStages, plAccessFlags afterAccesses)
+{
 }
 
 void
diff --git a/extensions/pl_graphics_vulkan.c b/extensions/pl_graphics_vulkan.c
