From 224355af69c377ef4175a2d66df2f7a97398b28a Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Wed, 30 Sep 2026 10:15:40 -0400
Subject: [PATCH] docs: Updated docs on SDL_LockTexture().
Reference https://github.com/libsdl-org/sdlwiki/issues/448#issuecomment-5907032640
---
include/SDL_render.h | 11 ++++++++++-
1 file changed, 10 insertions(+), 1 deletion(-)
diff --git a/include/SDL_render.h b/include/SDL_render.h
index 5ddeea6b81d3a..7c08fc6ccc83d 100644
--- a/include/SDL_render.h
+++ b/include/SDL_render.h
@@ -664,11 +664,20 @@ extern DECLSPEC int SDLCALL SDL_UpdateNVTexture(SDL_Texture * texture,
* As an optimization, the pixels made available for editing don't necessarily
* contain the old texture data. This is a write-only operation, and if you
* need to keep a copy of the texture data you should do that at the
- * application level.
+ * application level. If the existing texture contents happen to be in the
+ * locked buffer, it is purely coincidental.
*
* You must use SDL_UnlockTexture() to unlock the pixels and apply any
* changes.
*
+ * Every pixel must be initialized by the caller, or uninitialized data will
+ * be uploaded to the texture during unlock.
+ *
+ * `pitch` may be larger than the bytes needed for a row of pixels, as there
+ * might be padding included. Use `(y * pitch) + (x * pixel_size_in_bytes)` to
+ * write to the first byte of the pixel at `(x, y)` in the locked texture area,
+ * where `(0, 0)` is the top-left corner of the area.
+ *
* \param texture the texture to lock for access, which was created with
* `SDL_TEXTUREACCESS_STREAMING`.
* \param rect an SDL_Rect structure representing the area to lock for access;