SDL3pp
A slim C++ wrapper for SDL3
Loading...
Searching...
No Matches
Public Member Functions | List of all members
SDL::SurfaceRef Struct Reference

Handle to a non owned surface. More...

Inheritance diagram for SDL::SurfaceRef:
Inheritance graph
[legend]

Public Member Functions

constexpr SurfaceRef (const SurfaceRef &other)
 Copy constructor.
 
constexpr SurfaceRef (SurfaceRef &&other)
 Move constructor.
 
constexpr ~SurfaceRef ()=default
 Default constructor.
 
SurfaceRefoperator= (SurfaceRef other)
 Assignment operator.
 
void reset (SDL_Surface *newResource={})
 Free a surface.
 
 SurfaceBase (StringParam file)
 Load an image from a filesystem path into a software surface.
 
 SurfaceBase (IOStreamBase &src)
 Load an image from a IOStreamBase into a software surface.
 
 SurfaceBase (const SDL_Point &size, PixelFormat format)
 Allocate a new surface with a specific pixel format.
 
 SurfaceBase (const SDL_Point &size, PixelFormat format, void *pixels, int pitch)
 Allocate a new surface with a specific pixel format and existing pixel data.
 
- Public Member Functions inherited from SDL::SurfaceBase
 SurfaceBase (StringParam file)
 Load an image from a filesystem path into a software surface.
 
 SurfaceBase (IOStreamBase &src)
 Load an image from a IOStreamBase into a software surface.
 
 SurfaceBase (const SDL_Point &size, PixelFormat format)
 Allocate a new surface with a specific pixel format.
 
 SurfaceBase (const SDL_Point &size, PixelFormat format, void *pixels, int pitch)
 Allocate a new surface with a specific pixel format and existing pixel data.
 
PropertiesRef GetProperties () const
 Get the properties associated with a surface.
 
void SetColorspace (Colorspace colorspace)
 Set the colorspace used by a surface.
 
Colorspace GetColorspace () const
 Get the colorspace used by a surface.
 
PaletteRef CreatePalette ()
 Create a palette and associate it with a surface.
 
void SetPalette (PaletteBase &palette)
 Set the palette used by a surface.
 
PaletteRef GetPalette () const
 Get the palette used by a surface.
 
void AddAlternateImage (SurfaceBase &image)
 Add an alternate version of a surface.
 
bool HasAlternateImages () const
 Return whether a surface has alternate versions available.
 
OwnArray< SurfaceRefGetImages () const
 Get an array including all versions of a surface.
 
void RemoveAlternateImages ()
 Remove all alternate versions of a surface.
 
constexpr bool MustLock () const
 Evaluates to true if the surface needs to be locked before access.
 
SurfaceLock Lock () &
 Set up a surface for directly accessing the pixels.
 
void SetRLE (bool enabled)
 Set the RLE acceleration hint for a surface.
 
bool HasRLE () const
 Returns whether the surface is RLE enabled.
 
void SetColorKey (Color key)
 Set the color key (transparent pixel) in a surface.
 
void SetColorKey (std::optional< Uint32 > key)
 Set the color key (transparent pixel) in a surface.
 
void ClearColorKey ()
 Unset the color key (transparent pixel) in a surface.
 
bool HasColorKey () const
 Returns whether the surface has a color key.
 
Color GetColorKey () const
 Get the color key (transparent pixel) for a surface.
 
void GetColorKey (Color *key) const
 Get the color key (transparent pixel) for a surface.
 
void GetColorKey (Uint32 *key) const
 Get the color key (transparent pixel) for a surface.
 
void SetColorMod (Uint8 r, Uint8 g, Uint8 b)
 Set an additional color value multiplied into blit operations.
 
void GetColorMod (Uint8 *r, Uint8 *g, Uint8 *b) const
 Get the additional color value multiplied into blit operations.
 
void SetAlphaMod (Uint8 alpha)
 Set an additional alpha value used in blit operations.
 
Uint8 GetAlphaMod () const
 Get the additional alpha value used in blit operations.
 
void SetMod (Color color)
 Set an additional color and alpha value multiplied into blit operations.
 
Color GetMod () const
 Get the additional color and alpha value multiplied into blit operations.
 
void SetBlendMode (BlendMode blendMode)
 Set the blend mode used for blit operations.
 
BlendMode GetBlendMode () const
 Get the blend mode used for blit operations.
 
bool SetClipRect (OptionalRef< const SDL_Rect > rect)
 Set the clipping rectangle for a surface.
 
void ResetClipRect ()
 Disable the clipping rectangle for a surface.
 
Rect GetClipRect () const
 Get the clipping rectangle for a surface.
 
void Flip (FlipMode flip)
 Flip a surface vertically or horizontally.
 
Surface Duplicate () const
 Creates a new surface identical to the existing surface.
 
Surface Scale (int width, int height, ScaleMode scaleMode) const
 Creates a new surface identical to the existing surface, scaled to the desired size.
 
Surface Convert (PixelFormat format) const
 Copy an existing surface to a new surface of the specified format.
 
Surface Convert (PixelFormat format, PaletteBase &palette, Colorspace colorspace, PropertiesBase &props) const
 Copy an existing surface to a new surface of the specified format and colorspace.
 
void PremultiplyAlpha (bool linear)
 Premultiply the alpha in a surface.
 
void Clear (SDL_FColor color)
 Clear a surface with a specific color, with floating point precision.
 
void Fill (SDL_Color color)
 Perform a fast fill of a rectangle with a specific color.
 
void Fill (Uint32 color)
 Perform a fast fill of a rectangle with a specific color.
 
void FillRect (const SDL_Rect &rect, SDL_Color color)
 Perform a fast fill of a rectangle with a specific color.
 
void FillRect (const SDL_Rect &rect, Uint32 color)
 Perform a fast fill of a rectangle with a specific color.
 
void FillRects (SpanRef< const SDL_Rect > rects, SDL_Color color)
 Perform a fast fill of a set of rectangles with a specific color.
 
void FillRects (SpanRef< const SDL_Rect > rects, Uint32 color)
 Perform a fast fill of a set of rectangles with a specific color.
 
void Blit (const SurfaceBase &src, OptionalRef< const SDL_Rect > srcrect, const SDL_Point &dstpos)
 Performs a fast blit from the source surface to the destination surface with clipping.
 
void Blit (const SurfaceBase &src, OptionalRef< const SDL_Rect > srcrect, OptionalRef< const SDL_Rect > dstrect)
 Performs a fast blit from the source surface to the destination surface with clipping.
 
void BlitUnchecked (const SurfaceBase &src, const SDL_Rect &srcrect, const SDL_Rect &dstrect)
 Perform low-level surface blitting only.
 
void BlitScaled (const SurfaceBase &src, OptionalRef< const SDL_Rect > srcrect, OptionalRef< const SDL_Rect > dstrect, ScaleMode scaleMode)
 Perform a scaled blit to a destination surface, which may be of a different format.
 
void BlitUncheckedScaled (const SurfaceBase &src, const SDL_Rect &srcrect, const SDL_Rect &dstrect, ScaleMode scaleMode)
 Perform low-level surface scaled blitting only.
 
void Stretch (const SurfaceBase &src, const SDL_Rect &srcrect, const SDL_Rect &dstrect, ScaleMode scaleMode)
 Perform a stretched pixel copy from one surface to another.
 
void BlitTiled (const SurfaceBase &src, OptionalRef< const SDL_Rect > srcrect, OptionalRef< const SDL_Rect > dstrect)
 Perform a tiled blit to a destination surface, which may be of a different format.
 
void BlitTiledWithScale (const SurfaceBase &src, OptionalRef< const SDL_Rect > srcrect, float scale, SDL_ScaleMode scaleMode, OptionalRef< const SDL_Rect > dstrect)
 Perform a scaled and tiled blit to a destination surface, which may be of a different format.
 
void Blit9Grid (const SurfaceBase &src, OptionalRef< const SDL_Rect > srcrect, int left_width, int right_width, int top_height, int bottom_height, OptionalRef< const SDL_Rect > dstrect)
 Perform a scaled blit using the 9-grid algorithm to a destination surface, which may be of a different format.
 
void Blit9GridWithScale (const SurfaceBase &src, OptionalRef< const SDL_Rect > srcrect, int left_width, int right_width, int top_height, int bottom_height, float scale, SDL_ScaleMode scaleMode, OptionalRef< const SDL_Rect > dstrect)
 Perform a scaled blit using the 9-grid algorithm to a destination surface, which may be of a different format.
 
Uint32 MapColor (SDL_Color color) const
 Map an RGBA quadruple to a pixel value for a surface.
 
Uint32 MapColor (Uint8 r, Uint8 g, Uint8 b) const
 Map an RGB triple to an opaque pixel value for a surface.
 
Uint32 MapColor (Uint8 r, Uint8 g, Uint8 b, Uint8 a) const
 Map an RGBA quadruple to a pixel value for a surface.
 
Color ReadPixel (const SDL_Point &p) const
 This function prioritizes correctness over speed: it is suitable for unit tests, but is not intended for use in a game engine.
 
void ReadPixel (const SDL_Point &p, SDL_Color *c) const
 This function prioritizes correctness over speed: it is suitable for unit tests, but is not intended for use in a game engine.
 
void ReadPixel (const SDL_Point &p, SDL_FColor *c) const
 Retrieves a single pixel from a surface.
 
void ReadPixel (const SDL_Point &p, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a) const
 Retrieves a single pixel from a surface.
 
void ReadPixel (const SDL_Point &p, float *r, float *g, float *b, float *a) const
 Retrieves a single pixel from a surface.
 
void WritePixel (const SDL_Point &p, SDL_Color c)
 Writes a single pixel to a surface.
 
void WritePixel (const SDL_Point &p, SDL_FColor c)
 Writes a single pixel to a surface.
 
int GetWidth () const
 Get the width in pixels.
 
int GetHeight () const
 Get the height in pixels.
 
Point GetSize () const
 Get the size in pixels.
 
PixelFormat GetFormat () const
 Get the pixel format.
 
constexpr Resource (T resource={})
 Constructs the underlying resource.
 
constexpr Resource (std::nullptr_t)
 Equivalent to default ctor.
 
constexpr Resource (std::nullopt_t)
 Equivalent to default ctor.
 
 Resource (const Resource &other)=delete
 
 Resource (Resource &&other)=delete
 
- Public Member Functions inherited from SDL::Resource< SDL_Surface * >
constexpr Resource (SDL_Surface * resource={})
 Constructs the underlying resource.
 
constexpr Resource (std::nullptr_t)
 Equivalent to default ctor.
 
constexpr Resource (std::nullopt_t)
 Equivalent to default ctor.
 
 Resource (const Resource &other)=delete
 
 Resource (Resource &&other)=delete
 
Resourceoperator= (const Resource &other)=delete
 
Resourceoperator= (Resource &&other)=delete
 
constexpr operator bool () const
 True if contains a valid resource.
 
constexpr bool operator== (const Resource &other) const=default
 Comparison.
 
constexpr bool operator== (std::nullopt_t) const
 Comparison.
 
constexpr bool operator== (std::nullptr_t) const
 Comparison.
 
constexpr SDL_Surface * get () const
 Return contained resource;.
 
constexpr SDL_Surface * release (SDL_Surface * newResource={})
 Return contained resource and empties or replace value.
 
constexpr const SDL_Surface * operator-> () const
 Access to fields.
 
constexpr SDL_Surface * operator-> ()
 Access to fields.
 

Detailed Description

Category:
Resource
See also
SurfaceBase
Surface

Member Function Documentation

◆ reset()

void SDL::SurfaceRef::reset ( SDL_Surface *  newResource = {})
inline

It is safe to pass nullptr to this function.

Thread safety:
No other thread should be using the surface when it is freed.
Since
This function is available since SDL 3.2.0.
See also
SurfaceBase.SurfaceBase

◆ SurfaceBase() [1/4]

SDL::SurfaceBase::SurfaceBase ( const SDL_Point &  size,
PixelFormat  format 
)
inline

The pixels of the new surface are initialized to zero.

Parameters
sizethe width and height of the surface.
formatthe PixelFormat for the new surface's pixel format.
Postcondition
the new SurfaceBase structure that is created.
Exceptions
Erroron failure.
Thread safety:
It is safe to call this function from any thread.
Since
This function is available since SDL 3.2.0.

◆ SurfaceBase() [2/4]

SDL::SurfaceBase::SurfaceBase ( const SDL_Point &  size,
PixelFormat  format,
void *  pixels,
int  pitch 
)
inline

No copy is made of the pixel data. Pixel data is not managed automatically; you must free the surface before you free the pixel data.

Pitch is the offset in bytes from one row of pixels to the next, e.g. width*4 for PIXELFORMAT_RGBA8888.

You may pass nullptr for pixels and 0 for pitch to create a surface that you will fill in with valid values later.

Parameters
sizethe width and height of the surface.
formatthe PixelFormat for the new surface's pixel format.
pixelsa pointer to existing pixel data.
pitchthe number of bytes between each row, including padding.
Postcondition
the new SurfaceBase structure that is created.
Exceptions
Erroron failure.
Thread safety:
It is safe to call this function from any thread.
Since
This function is available since SDL 3.2.0.

◆ SurfaceBase() [3/4]

SDL::SurfaceBase::SurfaceBase ( IOStreamBase src)
inline

If available, this uses LoadSurface(IOStreamBase&), otherwise it uses LoadBMP(IOStreamBase&).

Parameters
srcan IOStreamBase to load an image from.
Postcondition
the new Surface with loaded contents on success.
Exceptions
Erroron failure.
See also
LoadSurface(StringParam)
LoadBMP(StringParam)

◆ SurfaceBase() [4/4]

SDL::SurfaceBase::SurfaceBase ( StringParam  file)
inline

If available, this uses LoadSurface(StringParam), otherwise it uses LoadBMP(StringParam).

Parameters
filea path on the filesystem to load an image from.
Postcondition
the new Surface with loaded contents on success.
Exceptions
Erroron failure.
See also
LoadSurface(StringParam)
LoadBMP(StringParam)

The documentation for this struct was generated from the following file: