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.

Detailed Description

Public Member Functions

Member Function Documentation

◆ info()

◆ getName()

◆ getID()

◆ assignSurface()

◆ setOwner()

◆ getOwner()

◆ optimize()

◆ rebuild()

◆ render()

◆ renderEx()

◆ applyFilter()

◆ setBlendMode()

◆ getBlendMode()

◆ setAlphaMod()

◆ getAlphaMod()

◆ setColorMod()

◆ getColorMod()

◆ setColorKey()

◆ getColorKey()

◆ getSurface()

◆ getWidth()

◆ getHeight()

◆ findTex()

◆ saveToBMP()

◆ saveToPNG()

◆ save() [1/2]

◆ save() [2/2]