NAME¶

SDL_LockTextureToSurface - Lock a portion of the texture for write-only pixel access, and expose it as a SDL surface.

HEADER FILE¶

Defined in SDL3/SDL_render.h

SYNOPSIS¶

#include "SDL3/SDL.h"

bool SDL_LockTextureToSurface(SDL_Texture *texture, const SDL_Rect *rect, SDL_Surface **surface);

DESCRIPTION¶

Besides providing an SDL_Surface
instead of raw pixel data, this function operates like SDL_LockTexture .

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.

The returned surface is freed internally after calling

SDL_UnlockTexture () or

SDL_DestroyTexture (). The caller should not free it.

FUNCTION PARAMETERS¶

texture

the texture to lock for access, which must be created with SDL_TEXTUREACCESS_STREAMING .

rect

a pointer to the rectangle to lock for access. If the rect is NULL, the entire texture will be locked.

surface

this is filled in with an SDL surface representing the locked area.

RETURN VALUE¶

Returns true on success or false on failure; call

SDL_GetError () for more information.

THREAD SAFETY¶

You may only call this function from the main thread.

AVAILABILITY¶

This function is available since SDL 3.1.3.

SEE ALSO¶

•(3), SDL_LockTexture(3), •(3), SDL_UnlockTexture(3)