sokol_gfx.h: new structs and functions to query internal resource attributes

sokol_gfx.h

@@ -234,6 +234,18 @@
         by calling sg_query_desc(). This will return an sg_desc struct with
         the default values patched in instead of any zero-initialized values
 
+    --- you can inspect various internal resource attributes via:
+
+            sg_buffer_info sg_query_buffer_info(sg_buffer buf)
+            sg_image_info sg_query_image_info(sg_image img)
+            sg_shader_info sg_query_shader_info(sg_shader shd)
+            sg_pipeline_info sg_query_pipeline_info(sg_pipeline pip)
+            sg_pass_info sg_query_pass_info(sg_pass pass)
+
+        ...please note that the returned info-structs are tied quite closely
+        to sokol_gfx.h internals, and may change more often than other
+        public API functions and structs.
+
     BACKEND-SPECIFIC TOPICS:
     ========================
     --- the GL backends need to know about the internal structure of uniform
@@ -1572,6 +1584,62 @@ typedef struct sg_trace_hooks {
     void (*err_bindings_invalid)(void* user_data);
 } sg_trace_hooks;
 
+/*
+    sg_buffer_info
+    sg_image_info
+    sg_shader_info
+    sg_pipeline_info
+    sg_pass_info
+
+    These structs contain various internal resource attributes which
+    might be useful for debug-inspection. Please don't rely on the
+    actual content of those structs too much, as they are quite closely
+    tied to sokol_gfx.h internals and may change more frequently than
+    the other public API elements.
+
+    The *_info structs are used as the return values of the following functions:
+
+    sg_query_buffer_info()
+    sg_query_image_info()
+    sg_query_shader_info()
+    sg_query_pipeline_info()
+    sg_query_pass_info()
+*/
+typedef struct sg_slot_info {
+    sg_resource_state state;    /* the current state of this resource slot */
+    uint32_t res_id;        /* type-neutral resource if (e.g. sg_buffer.id) */
+    uint32_t ctx_id;        /* the context this resource belongs to */
+} sg_slot_info;
+
+typedef struct sg_buffer_info {
+    sg_slot_info slot;              /* resource pool slot info */
+    uint32_t update_frame_index;    /* frame index of last sg_update_buffer() */
+    uint32_t append_frame_index;    /* frame index of last sg_append_buffer() */
+    int append_pos;                 /* current position in buffer for sg_append_buffer() */
+    bool append_overflow;           /* is buffer in overflow state (due to sg_append_buffer) */
+    int num_slots;                  /* number of renaming-slots for dynamically updated buffers */
+    int active_slot;                /* currently active write-slot for dynamically updated buffers */
+} sg_buffer_info;
+
+typedef struct sg_image_info {
+    sg_slot_info slot;              /* resource pool slot info */
+    uint32_t upd_frame_index;       /* frame index of last sg_update_image() */
+    int num_slots;                  /* number of renaming-slots for dynamically updated images */
+    int active_slot;                /* currently active write-slot for dynamically updated images */
+} sg_image_info;
+
+typedef struct sg_shader_info {
+    sg_slot_info slot;              /* resoure pool slot info */
+} sg_shader_info;
+
+typedef struct sg_pipeline_info {
+    sg_slot_info slot;              /* resource pool slot info */
+} sg_pipeline_info;
+
+typedef struct sg_pass_info {
+    sg_slot_info slot;              /* resource pool slot info */
+} sg_pass_info;
+
 /*
     sg_desc
 
@@ -1724,6 +1792,13 @@ SOKOL_API_DECL void sg_fail_shader(sg_shader shd_id);
 SOKOL_API_DECL void sg_fail_pipeline(sg_pipeline pip_id);
 SOKOL_API_DECL void sg_fail_pass(sg_pass pass_id);
 
+/* get internal resource attributes */
+SOKOL_API_DECL sg_buffer_info sg_query_buffer_info(sg_buffer buf);
+SOKOL_API_DECL sg_image_info sg_query_image_info(sg_image img);
+SOKOL_API_DECL sg_shader_info sg_query_shader_info(sg_shader shd);
+SOKOL_API_DECL sg_pipeline_info sg_query_pipeline_info(sg_pipeline pip);
+SOKOL_API_DECL sg_pass_info sg_query_pass_info(sg_pass pass);
+
 /* rendering contexts (optional) */
 SOKOL_API_DECL sg_context sg_setup_context(void);
 SOKOL_API_DECL void sg_activate_context(sg_context ctx_id);
@@ -9973,6 +10048,84 @@ SOKOL_API_IMPL void sg_pop_debug_group(void) {
     _SG_TRACE_NOARGS(pop_debug_group);
 }
 
+SOKOL_API_IMPL sg_buffer_info sg_query_buffer_info(sg_buffer buf_id) {
+    sg_buffer_info info;
+    memset(&info, 0, sizeof(info));
+    const _sg_buffer_t* buf = _sg_lookup_buffer(&_sg.pools, buf_id.id);
+    if (buf) {
+        info.slot.state = buf->slot.state;
+        info.slot.res_id = buf->slot.id;
+        info.slot.ctx_id = buf->slot.ctx_id;
+        info.update_frame_index = buf->update_frame_index;
+        info.append_frame_index = buf->append_frame_index;
+        info.append_pos = buf->append_pos;
+        info.append_overflow = buf->append_overflow;
+        #if defined(SOKOL_D3D11)
+        info.num_slots = 1;
+        info.active_slot = 0;
+        #else
+        info.num_slots = buf->num_slots;
+        info.active_slot = buf->active_slot;
+        #endif
+    }
+    return info;
+}
+
+SOKOL_API_IMPL sg_image_info sg_query_image_info(sg_image img_id) {
+    sg_image_info info;
+    memset(&info, 0, sizeof(info));
+    const _sg_image_t* img = _sg_lookup_image(&_sg.pools, img_id.id);
+    if (img) {
+        info.slot.state = img->slot.state;
+        info.slot.res_id = img->slot.id;
+        info.slot.ctx_id = img->slot.ctx_id;
+        #if defined(SOKOL_D3D11)
+        info.num_slots = 1;
+        info.active_slot = 0;
+        #else
+        info.num_slots = img->num_slots;
+        info.active_slot = img->active_slot;
+        #endif
+    }
+    return info;
+}
+
+SOKOL_API_IMPL sg_shader_info sg_query_shader_info(sg_shader shd_id) {
+    sg_shader_info info;
+    memset(&info, 0, sizeof(info));
+    const _sg_shader_t* shd = _sg_lookup_shader(&_sg.pools, shd_id.id);
+    if (shd) {
+        info.slot.state = shd->slot.state;
+        info.slot.res_id = shd->slot.id;
+        info.slot.ctx_id = shd->slot.ctx_id;
+    }
+    return info;
+}
+
+SOKOL_API_IMPL sg_pipeline_info sg_query_pipeline_info(sg_pipeline pip_id) {
+    sg_pipeline_info info;
+    memset(&info, 0, sizeof(info));
+    const _sg_pipeline_t* pip = _sg_lookup_pipeline(&_sg.pools, pip_id.id);
+    if (pip) {
+        info.slot.state = pip->slot.state;
+        info.slot.res_id = pip->slot.id;
+        info.slot.ctx_id = pip->slot.ctx_id;
+    }
+    return info;
+}
+
+SOKOL_API_IMPL sg_pass_info sg_query_pass_info(sg_pass pass_id) {
+    sg_pass_info info;
+    memset(&info, 0, sizeof(info));
+    const _sg_pass_t* pass = _sg_lookup_pass(&_sg.pools, pass_id.id);
+    if (pass) {
+        info.slot.state = pass->slot.state;
+        info.slot.res_id = pass->slot.id;
+        info.slot.ctx_id = pass->slot.ctx_id;
+    }
+    return info;
+}
+
 /*--- DEPRECATED ---*/
 #ifndef SOKOL_NO_DEPRECATED
 SOKOL_API_IMPL void sg_apply_draw_state(const sg_draw_state* ds) {