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

Loading...
Searching...
No Matches
CRM64Pro::Image
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.
Uint32 | getID () const override
| Get the ID.
bool | assignSurface (SDL_Surface *pSurf, 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 *rSrc=nullptr, SDL_FRect *rDst=nullptr)
| Render the image.
Sint32 | renderEx (const double dAngle, const SDL_FPoint *poCenter=nullptr, const SDL_FlipMode rf=SDL_FLIP_NONE, Sint32 idRes=0, SDL_FRect *rSrc=nullptr, SDL_FRect *rDst=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 ()
| 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)
| 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)
| 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 *&pTex, Sint32 &idScreen)
| Get the texture for each screen of this image.
bool | saveToBMP (const string &sFile="")
| Export the image to a BMP file.
bool | saveToPNG (const string &sFile="")
| Save the image to an external PNG file.
Sint32 | save (const string &sCDCFile, const string &sResourceName="")
| Save the image to a CDC file.
Sint32 | save (const 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 | unused for the time being.

Returns
  true on success, or false on failure.

## ◆ getName()

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

Get the name.

Returns
  The object name.

## ◆ getID()

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

Get the ID.

Returns
  Object ID.

## ◆ assignSurface()

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

Assign a SDL_Surface to this image.

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

Parameters

  pSurf | 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
  true on success or false 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 * | rSrc = nullptr,
|  | SDL_FRect * | rDst = nullptr )

Render the image.

Parameters

  idRes | a valid screen or image handle. Default uses the default screen.
  rSrc | the source SDL_FRect structure or nullptr for the entire image. Default nullptr.
  rDst | the destination SDL_FRect structure or nullptr to match rSrc. 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 | ( | const double | dAngle,
|  | const SDL_FPoint * | poCenter = nullptr,
|  | const SDL_FlipMode | rf = SDL_FLIP_NONE,
|  | Sint32 | idRes = 0,
|  | SDL_FRect * | rSrc = nullptr,
|  | SDL_FRect * | rDst = nullptr )

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

Parameters

  dAngle | angle in degrees for the rotation.
  poCenter | SDL_FPoint pointer indicating the rotation center. Default nullptr rotates around rDst.w/2 and rDst.h/2.
  rf | "SDL_FlipMode" value for flipping actions.
  idRes | a valid screen or image handle. Default uses the default screen.
  rSrc | the source SDL_FRect structure or nullptr for the entire image. Default nullptr.
  rDst | the destination SDL_FRect structure or nullptr to match rSrc. 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.

## ◆ 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 | ( |  | ) |

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 )

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 (0-255). Negative value disables colorkey.
  iG | green color component (0-255). Negative value disables colorkey.
  iB | blue color component (0-255). Negative value disables colorkey.

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

Note
  Modifying colorkey after texture creation automatically calls rebuild() which is slow.

## ◆ getColorKey()

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

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
  SDL_Surface pointer on success or nullptr on failure.

Note
  Modifying the surface when there is any texture for a screen created, requires to call to rebuild() method for updating the texture(s).

Warning
  Removing this surface will probably cause an application crash.

## ◆ 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 *& | pTex,
|  | Sint32 & | idScreen )

Get the texture for each screen of this image.

Parameters

  iIndex | pointer to an integer containing 0 for find the first texture or the iIndex value of previous calls to this method.
  pTex | pointer to a SDL_Texture, nullptr when no texture is present.
  idScreen | pointer to the screen handle for which the texture is, when no texture is present it is set to -1.

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

## ◆ saveToBMP()

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

Export 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 an external 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 | ( | const 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.