Merge pull request #5031 from AmityWilder/safety-comments

Safety Comments for Sound/Texture Update Functions

Author: raysan5

parser/output/raylib_api.json

@@ -8529,7 +8529,7 @@
     },
     {
       "name": "UpdateTexture",
-      "description": "Update GPU texture with new data",
+      "description": "Update GPU texture with new data (pixels should be able to fill texture)",
       "returnType": "void",
       "params": [
         {
@@ -8544,7 +8544,7 @@
     },
     {
       "name": "UpdateTextureRec",
-      "description": "Update GPU texture rectangle with new data",
+      "description": "Update GPU texture rectangle with new data (pixels and rec should fit in texture)",
       "returnType": "void",
       "params": [
         {
@@ -11511,7 +11511,7 @@
     },
     {
       "name": "UpdateSound",
-      "description": "Update sound buffer with new data",
+      "description": "Update sound buffer with new data (data and frame count should fit in sound)",
       "returnType": "void",
       "params": [
         {

parser/output/raylib_api.lua

@@ -6264,7 +6264,7 @@ return {
     },
     {
       name = "UpdateTexture",
-      description = "Update GPU texture with new data",
+      description = "Update GPU texture with new data (pixels should be able to fill texture)",
       returnType = "void",
       params = {
         {type = "Texture2D", name = "texture"},
@@ -6273,7 +6273,7 @@ return {
     },
     {
       name = "UpdateTextureRec",
-      description = "Update GPU texture rectangle with new data",
+      description = "Update GPU texture rectangle with new data (pixels and rec should fit in texture)",
       returnType = "void",
       params = {
         {type = "Texture2D", name = "texture"},
@@ -7872,7 +7872,7 @@ return {
     },
     {
       name = "UpdateSound",
-      description = "Update sound buffer with new data",
+      description = "Update sound buffer with new data (data and frame count should fit in sound)",
       returnType = "void",
       params = {
         {type = "Sound", name = "sound"},

parser/output/raylib_api.txt

@@ -3271,13 +3271,13 @@ Function 364: UnloadRenderTexture() (1 input parameters)
 Function 365: UpdateTexture() (2 input parameters)
   Name: UpdateTexture
   Return type: void
-  Description: Update GPU texture with new data
+  Description: Update GPU texture with new data (pixels should be able to fill texture)
   Param[1]: texture (type: Texture2D)
   Param[2]: pixels (type: const void *)
 Function 366: UpdateTextureRec() (3 input parameters)
   Name: UpdateTextureRec
   Return type: void
-  Description: Update GPU texture rectangle with new data
+  Description: Update GPU texture rectangle with new data (pixels and rec should fit in texture)
   Param[1]: texture (type: Texture2D)
   Param[2]: rec (type: Rectangle)
   Param[3]: pixels (type: const void *)
@@ -4399,7 +4399,7 @@ Function 530: IsSoundValid() (1 input parameters)
 Function 531: UpdateSound() (3 input parameters)
   Name: UpdateSound
   Return type: void
-  Description: Update sound buffer with new data
+  Description: Update sound buffer with new data (data and frame count should fit in sound)
   Param[1]: sound (type: Sound)
   Param[2]: data (type: const void *)
   Param[3]: sampleCount (type: int)

parser/output/raylib_api.xml

@@ -2150,11 +2150,11 @@
         <Function name="UnloadRenderTexture" retType="void" paramCount="1" desc="Unload render texture from GPU memory (VRAM)">
             <Param type="RenderTexture2D" name="target" desc="" />
         </Function>
-        <Function name="UpdateTexture" retType="void" paramCount="2" desc="Update GPU texture with new data">
+        <Function name="UpdateTexture" retType="void" paramCount="2" desc="Update GPU texture with new data (pixels should be able to fill texture)">
             <Param type="Texture2D" name="texture" desc="" />
             <Param type="const void *" name="pixels" desc="" />
         </Function>
-        <Function name="UpdateTextureRec" retType="void" paramCount="3" desc="Update GPU texture rectangle with new data">
+        <Function name="UpdateTextureRec" retType="void" paramCount="3" desc="Update GPU texture rectangle with new data (pixels and rec should fit in texture)">
             <Param type="Texture2D" name="texture" desc="" />
             <Param type="Rectangle" name="rec" desc="" />
             <Param type="const void *" name="pixels" desc="" />
@@ -2940,7 +2940,7 @@
         <Function name="IsSoundValid" retType="bool" paramCount="1" desc="Checks if a sound is valid (data loaded and buffers initialized)">
             <Param type="Sound" name="sound" desc="" />
         </Function>
-        <Function name="UpdateSound" retType="void" paramCount="3" desc="Update sound buffer with new data">
+        <Function name="UpdateSound" retType="void" paramCount="3" desc="Update sound buffer with new data (data and frame count should fit in sound)">
             <Param type="Sound" name="sound" desc="" />
             <Param type="const void *" name="data" desc="" />
             <Param type="int" name="sampleCount" desc="" />

src/raudio.c

@@ -1037,6 +1037,8 @@ void UnloadSoundAlias(Sound alias)
 }
 
 // Update sound buffer with new data
+// NOTE 1: data format must match sound.stream.sampleSize
+// NOTE 2: frameCount must not exceed sound.frameCount
 void UpdateSound(Sound sound, const void *data, int frameCount)
 {
     if (sound.stream.buffer != NULL)

src/raylib.h

@@ -1424,8 +1424,8 @@ RLAPI bool IsTextureValid(Texture2D texture);
 RLAPI void UnloadTexture(Texture2D texture);                                                             // Unload texture from GPU memory (VRAM)
 RLAPI bool IsRenderTextureValid(RenderTexture2D target);                                                 // Check if a render texture is valid (loaded in GPU)
 RLAPI void UnloadRenderTexture(RenderTexture2D target);                                                  // Unload render texture from GPU memory (VRAM)
-RLAPI void UpdateTexture(Texture2D texture, const void *pixels);                                         // Update GPU texture with new data
-RLAPI void UpdateTextureRec(Texture2D texture, Rectangle rec, const void *pixels);                       // Update GPU texture rectangle with new data
+RLAPI void UpdateTexture(Texture2D texture, const void *pixels);                                         // Update GPU texture with new data (pixels should be able to fill texture)
+RLAPI void UpdateTextureRec(Texture2D texture, Rectangle rec, const void *pixels);                       // Update GPU texture rectangle with new data (pixels and rec should fit in texture)
 
 // Texture configuration functions
 RLAPI void GenTextureMipmaps(Texture2D *texture);                                                        // Generate GPU mipmaps for a texture
@@ -1646,7 +1646,7 @@ RLAPI Sound LoadSound(const char *fileName);                          // Load so
 RLAPI Sound LoadSoundFromWave(Wave wave);                             // Load sound from wave data
 RLAPI Sound LoadSoundAlias(Sound source);                             // Create a new sound that shares the same sample data as the source sound, does not own the sound data
 RLAPI bool IsSoundValid(Sound sound);                                 // Checks if a sound is valid (data loaded and buffers initialized)
-RLAPI void UpdateSound(Sound sound, const void *data, int sampleCount); // Update sound buffer with new data
+RLAPI void UpdateSound(Sound sound, const void *data, int sampleCount); // Update sound buffer with new data (data and frame count should fit in sound)
 RLAPI void UnloadWave(Wave wave);                                     // Unload wave data
 RLAPI void UnloadSound(Sound sound);                                  // Unload sound
 RLAPI void UnloadSoundAlias(Sound alias);                             // Unload a sound alias (does not deallocate sample data)

src/rtextures.c

@@ -4338,14 +4338,17 @@ void UnloadRenderTexture(RenderTexture2D target)
 }
 
 // Update GPU texture with new data
-// NOTE: pixels data must match texture.format
+// NOTE 1: pixels data must match texture.format
+// NOTE 2: pixels data must contain at least as many pixels as texture
 void UpdateTexture(Texture2D texture, const void *pixels)
 {
     rlUpdateTexture(texture.id, 0, 0, texture.width, texture.height, texture.format, pixels);
 }
 
 // Update GPU texture rectangle with new data
-// NOTE: pixels data must match texture.format
+// NOTE 1: pixels data must match texture.format
+// NOTE 2: pixels data must contain as many pixels as rec contains
+// NOTE 3: rec must fit completely within texture's width and height
 void UpdateTextureRec(Texture2D texture, Rectangle rec, const void *pixels)
 {
     rlUpdateTexture(texture.id, (int)rec.x, (int)rec.y, (int)rec.width, (int)rec.height, texture.format, pixels);