sokol_gfx.h: sg_query_buffer_will_overflow() tweaks:

- rename from sg_query_will_buffer_overflow()
- add test
- update changelog

CHANGELOG.md

@@ -1,5 +1,10 @@
 ## Updates
 
+- **03-Jul-2022**: A new sokol_gfx.h function ```bool sg_query_buffer_will_overflow(sg_buffer buf, size_t size)```
+which allows to check if a call to ```sg_append_buffer()``` would overflow the buffer. This
+is an alternative to the ```sg_query_buffer_overflow()``` function which only reports
+the overflow after the fact. Many thanks to @RandyGaul for the PR!
+
 - **29-Jun-2022**: In sokol_app.h with the D3D11 backend, if SOKOL_DEBUG is
 defined, and the D3D11 device creation fails, there's now a fallback code
 path which tries to create the device again without the D3D11_CREATE_DEVICE_DEBUG

sokol_gfx.h

@@ -128,7 +128,7 @@
     --- optionally update shader uniform data with:
 
             sg_apply_uniforms(sg_shader_stage stage, int ub_index, const sg_range* data)
-            
+
         Read the section 'UNIFORM DATA LAYOUT' to learn about the expected memory layout
         of the uniform data passed into sg_apply_uniforms().
 
@@ -250,7 +250,7 @@
         You can manually check to see if an overflow would occur before adding
         any data to a buffer by calling
 
-            bool sg_query_will_buffer_overflow(sg_buffer buf, size_t size)
+            bool sg_query_buffer_will_overflow(sg_buffer buf, size_t size)
 
         NOTE: Due to restrictions in underlying 3D-APIs, appended chunks of
         data will be 4-byte aligned in the destination buffer. This means
@@ -341,7 +341,7 @@
             with context information provided by sokol_app.h
 
     See the documention block of the sg_desc struct below for more information.
-    
+
 
     UNIFORM DATA LAYOUT:
     ====================
@@ -373,7 +373,7 @@
           SG_UNIFORMLAYOUT_STD140)
         - a list of the uniform block members types in the correct order they
           appear on the CPU side
-        
+
     For example if the GLSL shader has the following uniform declarations:
 
         uniform mat4 mvp;
@@ -417,7 +417,7 @@
     CROSS-BACKEND COMMON UNIFORM DATA LAYOUT
     ========================================
     For cross-platform / cross-3D-backend code it is important that the same uniform block
-    layout on the CPU side can be used for all sokol-gfx backends. To achieve this, 
+    layout on the CPU side can be used for all sokol-gfx backends. To achieve this,
     a common subset of the std140 layout must be used:
 
     - The uniform block layout hint in sg_shader_desc must be explicitely set to
@@ -443,7 +443,7 @@
         - ivec4 => 16
         - mat4  => 16
     - Arrays are only allowed for the following types: vec4, int4, mat4.
-          
+
     Note that the HLSL cbuffer layout rules are slightly different from the
     std140 layout rules, this means that the cbuffer declarations in HLSL code
     must be tweaked so that the layout is compatible with std140.
@@ -457,7 +457,7 @@
     --- The GL backends need to know about the internal structure of uniform
         blocks, and the texture sampler-name and -type. The uniform layout details
         are  described in the UNIFORM DATA LAYOUT section above.
-        
+
             // uniform block structure and texture image definition in sg_shader_desc:
             sg_shader_desc desc = {
                 // uniform block description (size and internal structure)
@@ -1355,35 +1355,35 @@ typedef enum sg_uniform_type {
 
 /*
     sg_uniform_layout
-    
+
     A hint for the interior memory layout of uniform blocks. This is
     only really relevant for the GL backend where the internal layout
     of uniform blocks must be known to sokol-gfx. For all other backends the
     internal memory layout of uniform blocks doesn't matter, sokol-gfx
     will just pass uniform data as a single memory blob to the
     3D backend.
-    
+
     SG_UNIFORMLAYOUT_NATIVE (default)
         Native layout means that a 'backend-native' memory layout
         is used. For the GL backend this means that uniforms
         are packed tightly in memory (e.g. there are no padding
         bytes).
-        
+
     SG_UNIFORMLAYOUT_STD140
         The memory layout is a subset of std140. Arrays are only
         allowed for the FLOAT4, INT4 and MAT4. Alignment is as
         is as follows:
-        
+
             FLOAT, INT:         4 byte alignment
             FLOAT2, INT2:       8 byte alignment
             FLOAT3, INT3:       16 byte alignment(!)
             FLOAT4, INT4:       16 byte alignment
             MAT4:               16 byte alignment
             FLOAT4[], INT4[]:   16 byte alignment
-            
+
         The overall size of the uniform block must be a multiple
         of 16.
-        
+
     For more information search for 'UNIFORM DATA LAYOUT' in the documentation block
     at the start of the header.
 */
@@ -1394,7 +1394,7 @@ typedef enum sg_uniform_layout {
     _SG_UNIFORMLAYOUT_NUM,
     _SG_UNIFORMLAYOUT_FORCE_U32 = 0x7FFFFFFF
 } sg_uniform_layout;
- 
+
 /*
     sg_cull_mode
 
@@ -2492,7 +2492,7 @@ SOKOL_GFX_API_DECL void sg_update_buffer(sg_buffer buf, const sg_range* data);
 SOKOL_GFX_API_DECL void sg_update_image(sg_image img, const sg_image_data* data);
 SOKOL_GFX_API_DECL int sg_append_buffer(sg_buffer buf, const sg_range* data);
 SOKOL_GFX_API_DECL bool sg_query_buffer_overflow(sg_buffer buf);
-SOKOL_GFX_API_DECL bool sg_query_will_buffer_overflow(sg_buffer buf, size_t size);
+SOKOL_GFX_API_DECL bool sg_query_buffer_will_overflow(sg_buffer buf, size_t size);
 
 /* rendering functions */
 SOKOL_GFX_API_DECL void sg_begin_default_pass(const sg_pass_action* pass_action, int width, int height);
@@ -14022,7 +14022,7 @@ _SOKOL_PRIVATE const char* _sg_validate_string(_sg_validate_error_t err) {
         case _SG_VALIDATE_SHADERDESC_UB_SIZE_MISMATCH:      return "size of uniform block members doesn't match uniform block size";
         case _SG_VALIDATE_SHADERDESC_UB_ARRAY_COUNT:        return "uniform array count must be >= 1";
         case _SG_VALIDATE_SHADERDESC_UB_STD140_ARRAY_TYPE:  return "uniform arrays only allowed for FLOAT4, INT4, MAT4 in std140 layout";
-        
+
         case _SG_VALIDATE_SHADERDESC_NO_CONT_IMGS:          return "shader images must occupy continuous slots";
         case _SG_VALIDATE_SHADERDESC_IMG_NAME:              return "GL backend requires uniform block member names";
         case _SG_VALIDATE_SHADERDESC_ATTR_NAMES:            return "GLES2 backend requires vertex attribute names";
@@ -15967,7 +15967,7 @@ SOKOL_API_IMPL bool sg_query_buffer_overflow(sg_buffer buf_id) {
     return result;
 }
 
-SOKOL_API_IMPL bool sg_query_will_buffer_overflow(sg_buffer buf_id, size_t size) {
+SOKOL_API_IMPL bool sg_query_buffer_will_overflow(sg_buffer buf_id, size_t size) {
     SOKOL_ASSERT(_sg.valid);
     _sg_buffer_t* buf = _sg_lookup_buffer(&_sg.pools, buf_id.id);
     bool result = false;

tests/functional/sokol_gfx_test.c

@@ -820,3 +820,19 @@ UTEST(sokol_gfx, pass_resource_states) {
     T(sg_query_pass_state(pass) == SG_RESOURCESTATE_INVALID);
     sg_shutdown();
 }
+
+UTEST(sokol_gfx, query_buffer_will_overflow) {
+    sg_setup(&(sg_desc){0});
+    sg_buffer buf = sg_make_buffer(&(sg_buffer_desc){
+        .size = 64,
+        .usage = SG_USAGE_STREAM
+    });
+    T(!sg_query_buffer_will_overflow(buf, 32));
+    T(!sg_query_buffer_will_overflow(buf, 64));
+    T(sg_query_buffer_will_overflow(buf, 65));
+    static const uint8_t data[32] = {0};
+    sg_append_buffer(buf, &SG_RANGE(data));
+    T(!sg_query_buffer_will_overflow(buf, 32));
+    T(sg_query_buffer_will_overflow(buf, 33));
+    sg_shutdown();
+}