Lock a portion of the texture for write-only pixel access, and expose it as a SDL surface. More...
Inheritance diagram for SDL::TextureSurfaceLock:
Collaboration diagram for SDL::TextureSurfaceLock:
Public Member Functions | |
| TextureSurfaceLock (TextureRef resource, OptionalRef< const RectRaw > rect=std::nullopt) | |
| Lock a portion of the texture for write-only pixel access, and expose it as a SDL surface. More... | |
| TextureSurfaceLock (const TextureSurfaceLock &other)=delete | |
| Copy constructor. | |
| constexpr | TextureSurfaceLock (TextureSurfaceLock &&other) noexcept |
| Move constructor. | |
| ~TextureSurfaceLock () | |
| Unlock a texture, uploading the changes to video memory, if needed. More... | |
| TextureSurfaceLock & | operator= (const TextureSurfaceLock &other)=delete |
| TextureSurfaceLock & | operator= (TextureSurfaceLock &&other) noexcept |
| Assignment operator. | |
| constexpr | operator bool () const |
| True if not locked. | |
| void | reset () |
| Unlock a texture, uploading the changes to video memory, if needed. More... | |
| TextureRef | get () |
| Get the reference to locked resource. | |
| void | release () |
| Releases the lock without unlocking. | |
 Public Member Functions inherited from SDL::Surface | |
| constexpr | Surface (std::nullptr_t=nullptr) noexcept |
| Default ctor. | |
| constexpr | Surface (const SurfaceRaw resource) noexcept |
| Constructs from SurfaceParam. More... | |
| constexpr | Surface (const Surface &other) |
| Copy constructor. | |
| constexpr | Surface (Surface &&other) noexcept |
| Move constructor. | |
| Surface (const PointRaw &size, PixelFormat format) | |
| Allocate a new surface with a specific pixel format. More... | |
| Surface (const PointRaw &size, PixelFormat format, void *pixels, int pitch) | |
| Allocate a new surface with a specific pixel format and existing pixel data. More... | |
| Surface (StringParam file) | |
| Load an image from a filesystem path into a software surface. More... | |
| Surface (IOStreamParam src, bool closeio=false) | |
| Load an image from an SDL data source into a software surface. More... | |
| constexpr const SurfaceRaw | operator-> () const noexcept |
| member access to underlying SurfaceRaw. | |
| constexpr SurfaceRaw | operator-> () noexcept |
| member access to underlying SurfaceRaw. | |
| ~Surface () | |
| Destructor. | |
| constexpr Surface & | operator= (Surface &&other) noexcept |
| Assignment operator. | |
| constexpr Surface & | operator= (const Surface &other) noexcept=default |
| Assignment operator. | |
| constexpr SurfaceRaw | get () const noexcept |
| Retrieves underlying SurfaceRaw. | |
| constexpr SurfaceRaw | release () noexcept |
| Retrieves underlying SurfaceRaw and clear this. | |
| constexpr auto | operator<=> (const Surface &other) const noexcept=default |
| Comparison. | |
| constexpr | operator bool () const noexcept |
| Converts to bool. | |
| constexpr | operator SurfaceParam () const noexcept |
| Converts to SurfaceParam. | |
| void | Destroy () |
| Free a surface. More... | |
| constexpr bool | MustLock () const |
| Evaluates to true if the surface needs to be locked before access. More... | |
| PropertiesRef | GetProperties () const |
| Get the properties associated with a surface. More... | |
| void | SetColorspace (Colorspace colorspace) |
| Set the colorspace used by a surface. More... | |
| Colorspace | GetColorspace () const |
| Get the colorspace used by a surface. More... | |
| Palette | CreatePalette () |
| Create a palette and associate it with a surface. More... | |
| void | SetPalette (PaletteParam palette) |
| Set the palette used by a surface. More... | |
| Palette | GetPalette () const |
| Get the palette used by a surface. More... | |
| void | AddAlternateImage (SurfaceParam image) |
| Add an alternate version of a surface. More... | |
| bool | HasAlternateImages () const |
| Return whether a surface has alternate versions available. More... | |
| OwnArray< SurfaceRaw > | GetImages () const |
| Get an array including all versions of a surface. More... | |
| void | RemoveAlternateImages () |
| Remove all alternate versions of a surface. More... | |
| SurfaceLock | Lock () |
| Set up a surface for directly accessing the pixels. More... | |
| void | Unlock (SurfaceLock &&lock) |
| Release a surface after directly accessing the pixels. More... | |
| void | SaveBMP (IOStreamParam dst, bool closeio=false) const |
| Save a surface to a seekable SDL data stream in BMP format. More... | |
| void | SaveBMP (StringParam file) const |
| Save a surface to a file in BMP format. More... | |
| void | SavePNG (IOStreamParam dst, bool closeio=false) const |
| Save a surface to a seekable SDL data stream in PNG format. More... | |
| void | SavePNG (StringParam file) const |
| Save a surface to a file in PNG format. More... | |
| void | SetRLE (bool enabled) |
| Set the RLE acceleration hint for a surface. More... | |
| bool | HasRLE () const |
| Returns whether the surface is RLE enabled. More... | |
| void | SetColorKey (std::optional< Uint32 > key) |
| Set the color key (transparent pixel) in a surface. More... | |
| void | ClearColorKey () |
| Unset the color key (transparent pixel) in a surface. More... | |
| bool | HasColorKey () const |
| Returns whether the surface has a color key. More... | |
| std::optional< Uint32 > | GetColorKey () const |
| Get the color key (transparent pixel) for a surface. More... | |
| void | SetColorMod (Uint8 r, Uint8 g, Uint8 b) |
| Set an additional color value multiplied into blit operations. More... | |
| void | GetColorMod (Uint8 *r, Uint8 *g, Uint8 *b) const |
| Get the additional color value multiplied into blit operations. More... | |
| void | SetAlphaMod (Uint8 alpha) |
| Set an additional alpha value used in blit operations. More... | |
| Uint8 | GetAlphaMod () const |
| Get the additional alpha value used in blit operations. More... | |
| void | SetMod (Color color) |
| Set an additional color and alpha value multiplied into blit operations. More... | |
| Color | GetMod () const |
| Get the additional color and alpha value multiplied into blit operations. More... | |
| void | SetBlendMode (BlendMode blendMode) |
| Set the blend mode used for blit operations. More... | |
| BlendMode | GetBlendMode () const |
| Get the blend mode used for blit operations. More... | |
| bool | SetClipRect (OptionalRef< const RectRaw > rect) |
| Set the clipping rectangle for a surface. More... | |
| void | ResetClipRect () |
| Disable the clipping rectangle for a surface. More... | |
| Rect | GetClipRect () const |
| Get the clipping rectangle for a surface. More... | |
| void | Flip (FlipMode flip) |
| Flip a surface vertically or horizontally. More... | |
| Surface | Rotate (float angle) |
| Return a copy of a surface rotated clockwise a number of degrees. More... | |
| Surface | Duplicate () const |
| Creates a new surface identical to the existing surface. More... | |
| Surface | Scale (const PointRaw &size, ScaleMode scaleMode) const |
| Creates a new surface identical to the existing surface, scaled to the desired size. More... | |
| Surface | Convert (PixelFormat format) const |
| Copy an existing surface to a new surface of the specified format. More... | |
| Surface | Convert (PixelFormat format, PaletteParam palette, Colorspace colorspace, PropertiesParam props) const |
| Copy an existing surface to a new surface of the specified format and colorspace. More... | |
| void | PremultiplyAlpha (bool linear) |
| Premultiply the alpha in a surface. More... | |
| void | Clear (const FColorRaw &c) |
| Clear a surface with a specific color, with floating point precision. More... | |
| void | FillRect (OptionalRef< const RectRaw > rect, Uint32 color) |
| Perform a fast fill of a rectangle with a specific color. More... | |
| void | Fill (Uint32 color) |
| Perform a fast fill of a rectangle with a specific color. More... | |
| void | FillRects (SpanRef< const RectRaw > rects, Uint32 color) |
| Perform a fast fill of a set of rectangles with a specific color. More... | |
| void | Blit (SurfaceParam src, OptionalRef< const RectRaw > srcrect, OptionalRef< const RectRaw > dstrect) |
| Performs a fast blit from the source surface to the destination surface with clipping. More... | |
| void | BlitAt (SurfaceParam src, OptionalRef< const RectRaw > srcrect, const PointRaw &dstpos) |
| Performs a fast blit from the source surface to the destination surface with clipping. More... | |
| void | BlitUnchecked (SurfaceParam src, const RectRaw &srcrect, const RectRaw &dstrect) |
| Perform low-level surface blitting only. More... | |
| void | BlitScaled (SurfaceParam src, OptionalRef< const RectRaw > srcrect, OptionalRef< const RectRaw > dstrect, ScaleMode scaleMode) |
| Perform a scaled blit to a destination surface, which may be of a different format. More... | |
| void | BlitUncheckedScaled (SurfaceParam src, const RectRaw &srcrect, const RectRaw &dstrect, ScaleMode scaleMode) |
| Perform low-level surface scaled blitting only. More... | |
| void | Stretch (SurfaceParam src, OptionalRef< RectRaw > srcrect, OptionalRef< RectRaw > dstrect, ScaleMode scaleMode) |
| Perform a stretched pixel copy from one surface to another. More... | |
| void | BlitTiled (SurfaceParam src, OptionalRef< const RectRaw > srcrect, OptionalRef< const RectRaw > dstrect) |
| Perform a tiled blit to a destination surface, which may be of a different format. More... | |
| void | BlitTiledWithScale (SurfaceParam src, OptionalRef< const RectRaw > srcrect, float scale, ScaleMode scaleMode, OptionalRef< const RectRaw > dstrect) |
| Perform a scaled and tiled blit to a destination surface, which may be of a different format. More... | |
| void | Blit9Grid (SurfaceParam src, OptionalRef< const RectRaw > srcrect, int left_width, int right_width, int top_height, int bottom_height, OptionalRef< const RectRaw > dstrect, float scale=1, ScaleMode scaleMode=SCALEMODE_NEAREST) |
| Perform a scaled blit using the 9-grid algorithm to a destination surface, which may be of a different format. More... | |
| Uint32 | MapRGB (Uint8 r, Uint8 g, Uint8 b) const |
| Map an RGB triple to an opaque pixel value for a surface. More... | |
| Uint32 | MapRGBA (ColorRaw c) const |
| Map an RGBA quadruple to a pixel value for a surface. More... | |
| void | ReadPixel (const PointRaw &p, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a) const |
| Retrieves a single pixel from a surface. More... | |
| Color | ReadPixel (const PointRaw &p) const |
| Retrieves a single pixel from a surface. More... | |
| void | ReadPixelFloat (const PointRaw &p, float *r, float *g, float *b, float *a) const |
| Retrieves a single pixel from a surface. More... | |
| FColor | ReadPixelFloat (const PointRaw &p) const |
| Retrieves a single pixel from a surface. More... | |
| void | WritePixel (const PointRaw &p, ColorRaw c) |
| Writes a single pixel to a surface. More... | |
| void | WritePixelFloat (const PointRaw &p, const FColorRaw &c) |
| Writes a single pixel to a surface. More... | |
| constexpr int | GetWidth () const |
| Get the width in pixels. | |
| constexpr int | GetHeight () const |
| Get the height in pixels. | |
| constexpr Point | GetSize () const |
| Get the size in pixels. | |
| constexpr int | GetPitch () const |
| Get pitch in bytes. | |
| constexpr PixelFormat | GetFormat () const |
| Get the pixel format. | |
| constexpr void * | GetPixels () const |
| Get the pixels. | |
Additional Inherited Members | |
| Static Public Member Functions inherited from SDL::Surface | |
| static constexpr Surface | Borrow (SurfaceParam resource) |
| Safely borrows the from SurfaceParam. More... | |
| static Surface | LoadBMP (IOStreamParam src, bool closeio=false) |
| Load a BMP image from a seekable SDL data stream. More... | |
| static Surface | LoadBMP (StringParam file) |
| Load a BMP image from a file. More... | |
| static Surface | LoadPNG (IOStreamParam src, bool closeio=false) |
| Load a PNG image from a seekable SDL data stream. More... | |
| static Surface | LoadPNG (StringParam file) |
| Load a PNG image from a file. More... | |
Detailed Description
Besides providing an Surface instead of raw pixel data, this function operates like Texture.Lock.
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 Texture.Unlock() to unlock the pixels and apply any changes.
The returned surface is freed internally after calling Texture.Unlock() or Texture.Destroy(). The caller should not free it.
- Since
- This class is available since SDL 3.2.0.
- See also
- Texture.Lock
- Texture.Unlock
Constructor & Destructor Documentation
◆ ~TextureSurfaceLock()
|
inline |
Warning: Please note that Texture.Lock() is intended to be write-only; it will not guarantee the previous contents of the texture will be provided. You must fully initialize any area of a texture that you lock before unlocking it, as the pixels might otherwise be uninitialized memory.
Which is to say: locking and immediately unlocking a texture can result in corrupted textures, depending on the renderer in use.
- Thread safety:
- This function should only be called on the main thread.
- Since
- This function is available since SDL 3.2.0.
- See also
- Texture.Lock
The documentation for this class was generated from the following file:
- SDL3pp/SDL3pp_render.h
