(This is the documentation for SDL3, which is the current stable version. SDL2 was the previous version!)

SDL_LockTexture

Lock a portion of the texture for write-only pixel access.

Header File

Syntax

bool SDL_LockTexture(SDL_Texture *texture,
                const SDL_Rect *rect,
                void **pixels, int *pitch);

Function Parameters

SDL_Texture *	texture	the texture to lock for access, which was created with `SDL_TEXTUREACCESS_STREAMING`.
const SDL_Rect *	rect	an SDL_Rect structure representing the area to lock for access; NULL to lock the entire texture.
void **	pixels	this is filled in with a pointer to the locked pixels, appropriately offset by the locked area.
int *	pitch	this is filled in with the pitch of the locked pixels; the pitch is the length of one row in bytes.

Return Value

(bool) Returns true on success or false if the texture is not valid or was not created with SDL_TEXTUREACCESS_STREAMING; call SDL_GetError() for more information.

Remarks

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.

You must use SDL_UnlockTexture() to unlock the pixels and apply any changes.

Thread Safety

This function should only be called on the main thread.

Version

This function is available since SDL 3.1.3.