| CRM64Pro GDK v0.19.0 A free cross-platform game development kit built on top of SDL 3.0

Loading...
Searching...
No Matches
CRM64Pro::Imagefinal
Graphics modules » Image

Image Object class. More...

## Detailed Description

Image Object class.

## Public Member Functions
bool | info (Sint32 iMode=0) override
| Request Image object information.
const string & | getName () const override
| Get the name.
Sint32 | getID () const override
| Get the ID.
Sint32 | assignSurface (SDL_Surface *pSurface, Sint32 iOwnership=0)
| Assign a SDL_Surface to this image.
Sint32 | setOwner (Sint32 iOwner)
| Set the owner of this image.
Sint32 | getOwner () const
| Get the owner of this image.
Sint32 | optimize (Sint32 idScreen=0)
| Optimize the image for rendering on screens in the most efficient way.
bool | rebuild ()
| Rebuild texture(s).
bool | markDirty (const SDL_Rect *pRect=nullptr)
| Mark cached textures dirty after source surface modification.
Sint32 | render (Sint32 idRes=0, SDL_FRect *pSrc=nullptr, SDL_FRect *pDst=nullptr)
| Render the image.
Sint32 | renderEx (double dAngle, const SDL_FPoint *pCenter=nullptr, SDL_FlipMode rf=SDL_FLIP_NONE, Sint32 idRes=0, SDL_FRect *pSrc=nullptr, SDL_FRect *pDst=nullptr)
| Render the image with extended attributes: can rotate and flip the image.
Sint32 | applyFilter (eImageFilter eFilter, Sint32 iValue=0)
| Apply a filter to this image.
bool | setBlendMode (SDL_BlendMode bmValue)
| Set the alpha blending mode.
SDL_BlendMode | getBlendMode () const
| Get blend mode used for rendering this image.
bool | setAlphaMod (Sint32 iAlpha)
| Set the alpha modulation value.
Sint32 | getAlphaMod () const
| Get alpha modulation used for rendering this image.
bool | setColorMod (Uint8 iR, Uint8 iG, Uint8 iB)
| Set the color modulation value.
Sint32 | getColorMod (Uint8 &iR, Uint8 &iG, Uint8 &iB) const
| Get color modulation used for rendering this image.
Sint32 | setColorKey (Sint16 iR=-1, Sint16 iG=-1, Sint16 iB=-1)
| Set colorkey used for rendering this image.
Sint32 | getColorKey (Sint16 &iR, Sint16 &iG, Sint16 &iB) const
| Get colorkey used for rendering this image.
SDL_Surface * | getSurface ()
| Get the raw source surface of this image.
Sint32 | getWidth () const
| Get the image width.
Sint32 | getHeight () const
| Get the image height.
bool | saveToBMP (const string &sFile="")
| Save the image to a BMP file.
bool | saveToPNG (const string &sFile="")
| Save the image to a PNG file.
Sint32 | save (const string &sCDCFile, const string &sResourceName="")
| Save the image to a CDC file.
Sint32 | save (Sint32 idCDC, const string &sResourceName="")
| Save the image to a CDC file.

## Member Function Documentation

## ◆ info()

bool CRM64Pro::Image::info | ( | Sint32 | iMode = 0 | ) |
| override

Request Image object information.

Writes information to the default log.

Parameters

  iMode | Reserved for future use. Pass 0.

Returns
  true on success, or false on failure.

## ◆ getName()

const string & CRM64Pro::Image::getName | ( |  | ) | const
| override

Get the name.

Returns
  The object name.

## ◆ getID()

Sint32 CRM64Pro::Image::getID | ( |  | ) | const
| override

Get the ID.

Returns
  Object ID.

## ◆ assignSurface()

Sint32 CRM64Pro::Image::assignSurface | ( | SDL_Surface * | pSurface,
|  | Sint32 | iOwnership = 0 )

Assign a SDL_Surface to this image.

Used for loading the source surface to images created with ImageMgr::create().

Parameters

  pSurface | SDL_Surface pointer.
  iOwnership | 0 (default) creates an internal copy (original can be freed), any other value takes ownership (do not free if call succeeds).

Returns
  0 on success, or a negative error code on failure.

Note
  Once the image has a source surface, it cannot be replaced so this method will fail.

## ◆ setOwner()

Sint32 CRM64Pro::Image::setOwner | ( | Sint32 | iOwner | ) |

Set the owner of this image.

Parameters

  iOwner | Owner of the image.

Returns
  0 on success, or a negative error code on failure.

Note
  Only images belonging to ImageMgr can modify their owner.

## ◆ getOwner()

Sint32 CRM64Pro::Image::getOwner | ( |  | ) | const

Get the owner of this image.

Returns
  The owner or this image.

## ◆ optimize()

Sint32 CRM64Pro::Image::optimize | ( | Sint32 | idScreen = 0 | ) |

Optimize the image for rendering on screens in the most efficient way.

Parameters

  idScreen | a valid screen handle used to convert the image to the same format as the screen. The screen must be initialized.

Returns
  0 on success, or a negative error code on failure.

## ◆ rebuild()

bool CRM64Pro::Image::rebuild | ( |  | ) |

Rebuild texture(s).

This method recreates existing textures from the source surface.

Returns
  true on success, or false on failure.

Note
  It is a slow process. For normal source surface pixel edits, use markDirty() instead.

## ◆ markDirty()

bool CRM64Pro::Image::markDirty | ( | const SDL_Rect * | pRect = nullptr | ) |

Mark cached textures dirty after source surface modification.

Call this after modifying the SDL_Surface returned by getSurface().

Parameters

  pRect | optional dirty rectangle in image coordinates, or nullptr to mark the full image dirty.

Returns
  true on success, or false if the image has no source surface.

Note
  Dirty textures are synchronized lazily before the next screen render. This is cheaper than rebuild() for normal pixel edits.
  GFX drawing methods that target an image call this automatically; direct SDL_Surface edits must call it manually.

## ◆ render()

Sint32 CRM64Pro::Image::render | ( | Sint32 | idRes = 0,
|  | SDL_FRect * | pSrc = nullptr,
|  | SDL_FRect * | pDst = nullptr )

Render the image.

Parameters

  idRes | a valid screen or image handle. Default uses the default screen.
  pSrc | the source SDL_FRect structure or nullptr for the entire image. Default nullptr.
  pDst | the destination SDL_FRect structure or nullptr to match pSrc. Can stretch or shrink the image. Default nullptr.

Returns
  0 on success, or a negative error code on failure.

Note
  With multiple screens, it is more optimal to render all images on one screen, then pass to the next screen and so on.

## ◆ renderEx()

Sint32 CRM64Pro::Image::renderEx | ( | double | dAngle,
|  | const SDL_FPoint * | pCenter = nullptr,
|  | SDL_FlipMode | rf = SDL_FLIP_NONE,
|  | Sint32 | idRes = 0,
|  | SDL_FRect * | pSrc = nullptr,
|  | SDL_FRect * | pDst = nullptr )

Render the image with extended attributes: can rotate and flip the image.

Parameters

  dAngle | angle in degrees for the rotation.
  pCenter | SDL_FPoint pointer indicating the rotation center. Default nullptr rotates around pDst->w/2 and pDst->h/2.
  rf | "SDL_FlipMode" value for flipping actions.
  idRes | a valid screen or image handle. Default uses the default screen.
  pSrc | the source SDL_FRect structure or nullptr for the entire image. Default nullptr.
  pDst | the destination SDL_FRect structure or nullptr to match pSrc. Can stretch or shrink. Default nullptr.

Returns
  0 on success, or a negative error code on failure.

Note
  With multiple screens, it is more optimal to render all images on one screen, then pass to the next screen and so on.
  Rendering to another image only supports flip modes, rotation will not be applied.

## ◆ applyFilter()

Sint32 CRM64Pro::Image::applyFilter | ( | eImageFilter | eFilter,
|  | Sint32 | iValue = 0 )

Apply a filter to this image.

Works on stand-alone and parent images; children cannot apply a filter. As the image is shared between parent and children, applying a filter to a parent affects all children.

Parameters

  eFilter | Check ::eImageFilter enum for details.
  iValue | adjustable value for some filters.

Returns
  0 on success, or a negative error code on failure.

Note
  Applying a filter modifies the source surface and marks cached textures dirty. Texture data is synchronized lazily before the next screen render.

## ◆ setBlendMode()

bool CRM64Pro::Image::setBlendMode | ( | SDL_BlendMode | bmValue | ) |

Set the alpha blending mode.

Parameters

  bmValue | the SDL_BlendMode to use for blending.

Returns
  true on success, or false on failure.

Note
  This changes render state only; cached textures are not rebuilt.

## ◆ getBlendMode()

SDL_BlendMode CRM64Pro::Image::getBlendMode | ( |  | ) | const

Get blend mode used for rendering this image.

Returns
  SDL_BlendMode.

## ◆ setAlphaMod()

bool CRM64Pro::Image::setAlphaMod | ( | Sint32 | iAlpha | ) |

Set the alpha modulation value.

Parameters

  iAlpha | the alpha value. Ranges from 255 (opaque) to 0 (fully transparent).

Returns
  true on success, or false on failure.

Note
  This changes render state only; cached textures are not rebuilt.

## ◆ getAlphaMod()

Sint32 CRM64Pro::Image::getAlphaMod | ( |  | ) | const

Get alpha modulation used for rendering this image.

Returns
  It ranges from 255 (opaque) to 0 (fully transparent).

## ◆ setColorMod()

bool CRM64Pro::Image::setColorMod | ( | Uint8 | iR,
|  | Uint8 | iG,
|  | Uint8 | iB )

Set the color modulation value.

Parameters

  iR | the red color value.
  iG | the green color value.
  iB | the blue color value.

Returns
  true on success, or false on failure.

Note
  This changes render state only; cached textures are not rebuilt.

## ◆ getColorMod()

Sint32 CRM64Pro::Image::getColorMod | ( | Uint8 & | iR,
|  | Uint8 & | iG,
|  | Uint8 & | iB ) const

Get color modulation used for rendering this image.

Parameters

  iR | red color component value from 0 to 255.
  iG | green color component value from 0 to 255.
  iB | blue color component value from 0 to 255.

Returns
  0 on success, or a negative error code on failure.

## ◆ setColorKey()

Sint32 CRM64Pro::Image::setColorKey | ( | Sint16 | iR = -1,
|  | Sint16 | iG = -1,
|  | Sint16 | iB = -1 )

Set colorkey used for rendering this image.

Colorkey can only be modified on stand-alone images. Internally emulated using blending modes; if already set, it is not modified, otherwise SDL_BLENDMODE_BLEND is set.

Parameters

  iR | red color component. A negative value disables colorkey.
  iG | green color component. A negative value disables colorkey.
  iB | blue color component. A negative value disables colorkey.

Returns
  0 on success, or a negative error code on failure.

Note
  If any color component is negative, the complete colorkey is disabled. If all components are non-negative, each component must be in the [0, 255] range.
  Modifying colorkey changes source-surface color key state and rebuilds existing textures. Rebuild failure is reported as a negative error code.

## ◆ getColorKey()

Sint32 CRM64Pro::Image::getColorKey | ( | Sint16 & | iR,
|  | Sint16 & | iG,
|  | Sint16 & | iB ) const

Get colorkey used for rendering this image.

Parameters

  iR | red color component (0-255). Negative means colorkey is disabled.
  iG | green color component (0-255). Negative means colorkey is disabled.
  iB | blue color component (0-255). Negative means colorkey is disabled.

Returns
  0 on success, or a negative error code on failure.

## ◆ getSurface()

SDL_Surface * CRM64Pro::Image::getSurface | ( |  | ) |

Get the raw source surface of this image.

Returns
  Borrowed mutable SDL_Surface pointer, or nullptr on failure.

Note
  The returned pointer must not be destroyed or stored long-term. It remains valid until the Image is closed or its source surface is replaced.
  Parent and child images share the same source surface. Render attributes such as alpha, color modulation and blend mode are not applied by this getter.
  If the surface is modified directly after textures were created, markDirty() must be called to update those textures before the next screen render. GFX image-target drawing does this automatically.

Warning
  This pointer is provided for SDL interop only.

## ◆ getWidth()

Sint32 CRM64Pro::Image::getWidth | ( |  | ) | const

Get the image width.

Returns
  The image width in pixels.

## ◆ getHeight()

Sint32 CRM64Pro::Image::getHeight | ( |  | ) | const

Get the image height.

Returns
  The image height in pixels.

## ◆ saveToBMP()

bool CRM64Pro::Image::saveToBMP | ( | const string & | sFile = "" | ) |

Save the image to a BMP file.

If the BMP file already exists, it will be overwritten.

Parameters

  sFile | string containing [directory]+filename+[extension]. Ideally should have .bmp extension. Directory separators '\' and '/' are supported.

Returns
  true on success, or false on failure.

## ◆ saveToPNG()

bool CRM64Pro::Image::saveToPNG | ( | const string & | sFile = "" | ) |

Save the image to a PNG file.

If the PNG file already exists, it will be overwritten.

Parameters

  sFile | string containing [directory]+filename+[extension]. Ideally should have .png extension. Directory separators '\' and '/' are supported.

Returns
  true on success, or false on failure.

## ◆ save() [1/2]

Sint32 CRM64Pro::Image::save | ( | const string & | sCDCFile,
|  | const string & | sResourceName = "" )

Save the image to a CDC file.

Parameters

  sCDCFile | string containing [directory]+filename+[extension]. Directory separators '\' and '/' are supported.
  sResourceName | Optional resource name to use in the CDC. If empty (default), uses the Image object's internal name.

Returns
  0 on success, or a negative error code on failure.

Note
  If the image already exists, it will be overwritten. Cannot save child images.

## ◆ save() [2/2]

Sint32 CRM64Pro::Image::save | ( | Sint32 | idCDC,
|  | const string & | sResourceName = "" )

Save the image to a CDC file.

Parameters

  idCDC | CDC id.
  sResourceName | Optional resource name to use in the CDC. If empty (default), uses the Image object's internal name.

Returns
  0 on success, or a negative error code on failure.

Note
  If the image already exists, it will be overwritten. If the image is a child, it calls the save method of its parent.