Pipeline caching

include/SDL3/SDL_gpu.h

@@ -298,6 +298,19 @@ typedef struct SDL_GPUComputePipeline SDL_GPUComputePipeline;
  */
 typedef struct SDL_GPUGraphicsPipeline SDL_GPUGraphicsPipeline;
 
+/**
+ * An opaque handle representing a pipeline cache.
+ *
+ * Used during pipeline creation.
+ *
+ * \since This struct is available since SDL 3.1.3
+ *
+ * \sa SDL_CreateGPUPipelineCache
+ * \sa SDL_ReleaseGPUPipelineCache
+ * \sa SDL_FetchGPUPipelineCacheData
+ */
+typedef struct SDL_GPUPipelineCache SDL_GPUPipelineCache;
+
 /**
  * An opaque handle representing a command buffer.
  *
@@ -1700,6 +1713,22 @@ typedef struct SDL_GPUComputePipelineCreateInfo
     SDL_PropertiesID props;                 /**< A properties ID for extensions. Should be 0 if no extensions are needed. */
 } SDL_GPUComputePipelineCreateInfo;
 
+/**
+ * A structure specifying the parameters of a pipeline cache.
+ *
+ * \since This struct is available since SDL 3.1.3
+ *
+ * \sa SDL_CreateGPUPipelineCache
+ * \sa SDL_FetchGPUPipelineCacheData
+ */
+typedef struct SDL_GPUPipelineCacheCreateInfo
+{
+    size_t checksum_size;  /**< The size in bytes of the cache checksum. */
+    void*  checksum_data;  /**< A pointer to the checksum data. */
+    size_t cache_size;     /**< The size in bytes of the pipeline cache. */
+    void*  cache_data;     /**< A pointer to the cache data. */
+} SDL_GPUPipelineCacheCreateInfo;
+
 /**
  * A structure specifying the parameters of a color target used by a render
  * pass.
@@ -2009,6 +2038,7 @@ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDeviceWithProperties(
 #define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOLEAN        "SDL.gpu.device.create.shaders.msl"
 #define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN   "SDL.gpu.device.create.shaders.metallib"
 #define SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING "SDL.gpu.device.create.d3d12.semantic"
+#define SDL_PROP_GPU_PIPELINE_USE_CACHE                       "SDL.gpu.pipeline.use.cache"
 
 /**
  * Destroys a GPU context previously returned by SDL_CreateGPUDevice.
@@ -2136,6 +2166,43 @@ extern SDL_DECLSPEC SDL_GPUGraphicsPipeline *SDLCALL SDL_CreateGPUGraphicsPipeli
     SDL_GPUDevice *device,
     const SDL_GPUGraphicsPipelineCreateInfo *createinfo);
 
+/**
+ * Creates a pipeline cache object to be used during pipeline builds.
+ *
+ * \param device a GPU Context.
+ * \param createinfo a struct containing the pipeline cache data. Set everything to NULL/0 in order to force a cache rebuild
+ * \returns a pipeline cache object on success, or NULL on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 3.1.3.
+ *
+ * \sa SDL_CreatePipelineCache
+ * \sa SDL_ReleasePipelineCache
+ * \sa SDL_RetrievePipelineCacheData
+ */
+extern SDL_DECLSPEC SDL_GPUPipelineCache* SDLCALL SDL_CreateGPUPipelineCache(
+    SDL_GPUDevice* device,
+    const SDL_GPUPipelineCacheCreateInfo* createinfo);
+
+/**
+ * Fetches a pipeline cache object data. This can then be stored to disk and loaded on the next application run
+ *
+ * \param device a GPU Context.
+ * \param pipeline_cache pipeline cache object to fetch data from
+ * \param createinfo a struct that will contain the cache's serializable data 
+ * \returns true on success, or false on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 3.1.3.
+ *
+ * \sa SDL_CreatePipelineCache
+ * \sa SDL_ReleasePipelineCache
+ */
+extern SDL_DECLSPEC bool SDLCALL SDL_FetchGPUPipelineCacheData(
+    SDL_GPUDevice* device,
+    SDL_GPUPipelineCache* pipeline_cache,
+    SDL_GPUPipelineCacheCreateInfo* createinfo);
+
 /**
  * Creates a sampler object to be used when binding textures in a graphics
  * workflow.
@@ -2496,6 +2563,20 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUGraphicsPipeline(
     SDL_GPUDevice *device,
     SDL_GPUGraphicsPipeline *graphics_pipeline);
 
+/**
+ * Frees the given pipeline cache as soon as it is safe to do so.
+ *
+ * You must not reference the pipeline cache after calling this function.
+ *
+ * \param device a GPU context.
+ * \param pipeline_cache a pipeline cache to be destroyed.
+ *
+ * \since This function is available since SDL 3.1.3.
+ */
+extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUPipelineCache(
+    SDL_GPUDevice* device,
+    SDL_GPUPipelineCache* pipeline_cache);
+
 /**
  * Acquire a command buffer.
  *

src/dynapi/SDL_dynapi.sym

@@ -1205,6 +1205,9 @@ SDL3_0.0.0 {
     SDL_RunOnMainThread;
     SDL_SetGPUAllowedFramesInFlight;
     SDL_RenderTextureAffine;
+    SDL_CreateGPUPipelineCache;
+    SDL_FetchGPUPipelineCacheData;
+    SDL_ReleaseGPUPipelineCache;
     # extra symbols go here (don't modify this line)
   local: *;
 };

src/dynapi/SDL_dynapi_overrides.h

@@ -1230,3 +1230,6 @@
 #define SDL_RunOnMainThread SDL_RunOnMainThread_REAL
 #define SDL_SetGPUAllowedFramesInFlight SDL_SetGPUAllowedFramesInFlight_REAL
 #define SDL_RenderTextureAffine SDL_RenderTextureAffine_REAL
+#define SDL_CreateGPUPipelineCache SDL_CreateGPUPipelineCache_REAL
+#define SDL_FetchGPUPipelineCacheData SDL_FetchGPUPipelineCacheData_REAL
+#define SDL_ReleaseGPUPipelineCache SDL_ReleaseGPUPipelineCache_REAL

src/dynapi/SDL_dynapi_procs.h

@@ -1236,3 +1236,6 @@ SDL_DYNAPI_PROC(bool,SDL_IsMainThread,(void),(),return)
 SDL_DYNAPI_PROC(bool,SDL_RunOnMainThread,(SDL_MainThreadCallback a,void *b,bool c),(a,b,c),return)
 SDL_DYNAPI_PROC(bool,SDL_SetGPUAllowedFramesInFlight,(SDL_GPUDevice *a,Uint32 b),(a,b),return)
 SDL_DYNAPI_PROC(bool,SDL_RenderTextureAffine,(SDL_Renderer *a,SDL_Texture *b,const SDL_FRect *c,const SDL_FPoint *d,const SDL_FPoint *e,const SDL_FPoint *f),(a,b,c,d,e,f),return)
+SDL_DYNAPI_PROC(SDL_GPUPipelineCache*,SDL_CreateGPUPipelineCache,(SDL_GPUDevice *a,const SDL_GPUPipelineCacheCreateInfo *b),(a,b),return)
+SDL_DYNAPI_PROC(bool,SDL_FetchGPUPipelineCacheData,(SDL_GPUDevice *a,SDL_GPUPipelineCache *b,SDL_GPUPipelineCacheCreateInfo *c),(a,b,c),return)
+SDL_DYNAPI_PROC(void,SDL_ReleaseGPUPipelineCache,(SDL_GPUDevice *a,SDL_GPUPipelineCache *b),(a,b),)

src/gpu/SDL_gpu.c

@@ -862,6 +862,37 @@ SDL_GPUGraphicsPipeline *SDL_CreateGPUGraphicsPipeline(
         graphicsPipelineCreateInfo);
 }
 
+SDL_GPUPipelineCache* SDL_CreateGPUPipelineCache(
+    SDL_GPUDevice* device,
+    const SDL_GPUPipelineCacheCreateInfo* createinfo)
+{
+    CHECK_DEVICE_MAGIC(device, NULL);
+    if (createinfo == NULL) {
+        SDL_InvalidParamError("createinfo");
+        return NULL;
+    }
+
+    return device->CreatePipelineCache(device->driverData, createinfo);
+}
+
+bool SDL_FetchGPUPipelineCacheData(
+    SDL_GPUDevice* device,
+    SDL_GPUPipelineCache* pipeline_cache,
+    SDL_GPUPipelineCacheCreateInfo* createinfo)
+{
+    CHECK_DEVICE_MAGIC(device, false);
+    if (pipeline_cache == NULL) {
+        SDL_InvalidParamError("pipeline_cache");
+        return false;
+    }
+    if (createinfo == NULL) {
+        SDL_InvalidParamError("createinfo");
+        return false;
+    }
+
+    return device->FetchPipelineCacheData(device->driverData, pipeline_cache, createinfo);
+}
+
 SDL_GPUSampler *SDL_CreateGPUSampler(
     SDL_GPUDevice *device,
     const SDL_GPUSamplerCreateInfo *createinfo)
@@ -1279,6 +1310,20 @@ void SDL_ReleaseGPUGraphicsPipeline(
         graphics_pipeline);
 }
 
+void SDL_ReleaseGPUPipelineCache(
+    SDL_GPUDevice* device,
+    SDL_GPUPipelineCache* pipeline_cache)
+{
+    CHECK_DEVICE_MAGIC(device, );
+    if (pipeline_cache == NULL) {
+        return;
+    }
+
+    device->ReleasePipelineCache(
+        device->driverData,
+        pipeline_cache);
+}
+
 // Command Buffer
 
 SDL_GPUCommandBuffer *SDL_AcquireGPUCommandBuffer(

src/gpu/SDL_sysgpu.h

@@ -459,6 +459,15 @@ struct SDL_GPUDevice
         SDL_GPURenderer *driverData,
         const SDL_GPUGraphicsPipelineCreateInfo *createinfo);
 
+    SDL_GPUPipelineCache* (*CreatePipelineCache)(
+        SDL_GPURenderer* driverData,
+        const SDL_GPUPipelineCacheCreateInfo* createinfo);
+
+    bool (*FetchPipelineCacheData)(
+        SDL_GPURenderer* driverData,
+        SDL_GPUPipelineCache* pipelineCache,
+        SDL_GPUPipelineCacheCreateInfo* createinfo);
+
     SDL_GPUSampler *(*CreateSampler)(
         SDL_GPURenderer *driverData,
         const SDL_GPUSamplerCreateInfo *createinfo);
@@ -534,6 +543,10 @@ struct SDL_GPUDevice
         SDL_GPURenderer *driverData,
         SDL_GPUGraphicsPipeline *graphicsPipeline);
 
+    void (*ReleasePipelineCache)(
+        SDL_GPURenderer* driverData,
+        SDL_GPUPipelineCache* pipelineCache);
+
     // Render Pass
 
     void (*BeginRenderPass)(
@@ -869,6 +882,8 @@ struct SDL_GPUDevice
     ASSIGN_DRIVER_FUNC(DestroyDevice, name)                 \
     ASSIGN_DRIVER_FUNC(CreateComputePipeline, name)         \
     ASSIGN_DRIVER_FUNC(CreateGraphicsPipeline, name)        \
+    ASSIGN_DRIVER_FUNC(CreatePipelineCache, name)           \
+    ASSIGN_DRIVER_FUNC(FetchPipelineCacheData, name)        \
     ASSIGN_DRIVER_FUNC(CreateSampler, name)                 \
     ASSIGN_DRIVER_FUNC(CreateShader, name)                  \
     ASSIGN_DRIVER_FUNC(CreateTexture, name)                 \
@@ -886,6 +901,7 @@ struct SDL_GPUDevice
     ASSIGN_DRIVER_FUNC(ReleaseShader, name)                 \
     ASSIGN_DRIVER_FUNC(ReleaseComputePipeline, name)        \
     ASSIGN_DRIVER_FUNC(ReleaseGraphicsPipeline, name)       \
+    ASSIGN_DRIVER_FUNC(ReleasePipelineCache, name)          \
     ASSIGN_DRIVER_FUNC(BeginRenderPass, name)               \
     ASSIGN_DRIVER_FUNC(BindGraphicsPipeline, name)          \
     ASSIGN_DRIVER_FUNC(SetViewport, name)                   \

src/gpu/d3d12/SDL_gpu_d3d12.c

@@ -2875,6 +2875,23 @@ static SDL_GPUGraphicsPipeline *D3D12_CreateGraphicsPipeline(
     return (SDL_GPUGraphicsPipeline *)pipeline;
 }
 
+static SDL_GPUPipelineCache* D3D12_CreatePipelineCache(
+    SDL_GPURenderer* driverData,
+    const SDL_GPUPipelineCacheCreateInfo* createinfo)
+{
+    // Not yet implemented
+    return NULL;
+}
+
+static bool D3D12_FetchPipelineCacheData(
+    SDL_GPURenderer* driverData,
+    SDL_GPUPipelineCache* pipelineCache,
+    SDL_GPUPipelineCacheCreateInfo* createinfo)
+{
+    // Not yet implemented
+    return false;
+}
+
 static SDL_GPUSampler *D3D12_CreateSampler(
     SDL_GPURenderer *driverData,
     const SDL_GPUSamplerCreateInfo *createinfo)
@@ -3854,6 +3871,13 @@ static void D3D12_INTERNAL_ReleaseBlitPipelines(SDL_GPURenderer *driverData)
     SDL_free(renderer->blitPipelines);
 }
 
+static void D3D12_ReleasePipelineCache(
+    SDL_GPURenderer* driverData,
+    SDL_GPUPipelineCache* pipelineCache)
+{
+   // Not yet implemented
+}
+
 // Render Pass
 
 static void D3D12_SetViewport(