| CRM64Pro GDK v0.18.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).
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 source surface of this image.
Sint32 | getWidth () const
| Get the image width.
Sint32 | getHeight () const
| Get the image height.
Sint32 | findTex (Sint32 &iIndex, SDL_Texture *&pTexture, Sint32 &idScreen)
| Get the texture for each screen of this image.
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 will rebuild any existing texture and it is used when the source surface is modified and the textures have to be "in-sync".

Returns
  true on success, or false on failure.

Note
  It is a slow process.

## ◆ 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 after a texture is created for a screen forces a slow rebuilding process. Rebuild failure is reported as a negative error code.

## ◆ 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
  Applying a filter after a texture is created for a screen forces a slow rebuilding process.

## ◆ 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
  Modifying alpha modulation after texture creation automatically calls rebuild() which is slow.

## ◆ 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
  Modifying color modulation after texture creation automatically calls rebuild() which is slow.

## ◆ 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 after texture creation automatically calls rebuild() which is slow. 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 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.
  If the surface is modified directly after textures were created, rebuild() must be called to update those textures.

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.

## ◆ findTex()

Sint32 CRM64Pro::Image::findTex | ( | Sint32 & | iIndex,
|  | SDL_Texture *& | pTexture,
|  | Sint32 & | idScreen )

Get the texture for each screen of this image.

Parameters

  iIndex | Input/output texture iterator index. Set to 0 to find the first texture; pass the value returned by the previous call to continue.
  pTexture | Output borrowed pointer to SDL_Texture, or nullptr when no texture is present.
  idScreen | Output screen handle for the returned texture; set to -1 when no texture is present.

Returns
  0 on success (a texture is returned), or a negative error code on failure.

Note
  The returned texture must not be destroyed or stored long-term. It remains valid until the Image texture is rebuilt, the Image is closed or the Screen is closed.

## ◆ 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.