CRM64Pro GDK  v0.94
A free cross-platform game development kit built on top of SDL 2.0
Classes | Functions
Image Manager

Classes

class  CRM64Pro::ImageObj
 
class  CRM64Pro::ImageMgr
 

Functions

Sint32 CRM64Pro::ImageObj::info (Sint32 iMode=0)
 
Sint32 CRM64Pro::ImageObj::getName (string &sName)
 
Uint32 CRM64Pro::ImageObj::getID ()
 
Sint32 CRM64Pro::ImageObj::assignSurface (SDL_Surface *pSurf, Sint32 iOwnership=0)
 
Sint32 CRM64Pro::ImageObj::setOwner (Sint32 iOwner)
 
Sint32 CRM64Pro::ImageObj::getOwner ()
 
Sint32 CRM64Pro::ImageObj::optimize (Sint32 idScreen=0)
 
Sint32 CRM64Pro::ImageObj::rebuild ()
 
Sint32 CRM64Pro::ImageObj::render (Sint32 idRes=0, SDL_Rect *rSrc=nullptr, SDL_Rect *rDst=nullptr)
 
Sint32 CRM64Pro::ImageObj::renderEx (const double dAngle, const SDL_Point *poCenter=nullptr, const SDL_RendererFlip rf=SDL_FLIP_NONE, Sint32 idRes=0, SDL_Rect *rSrc=nullptr, SDL_Rect *rDst=nullptr)
 
Sint32 CRM64Pro::ImageObj::applyFilter (eImageFilter eFilter, Sint32 iValue=0)
 
Sint32 CRM64Pro::ImageObj::setBlendMode (SDL_BlendMode bmValue)
 
SDL_BlendMode CRM64Pro::ImageObj::getBlendMode ()
 
Sint32 CRM64Pro::ImageObj::setAlphaMod (Uint8 iAlpha)
 
Uint8 CRM64Pro::ImageObj::getAlphaMod ()
 
Sint32 CRM64Pro::ImageObj::setColorMod (Uint8 iR, Uint8 iG, Uint8 iB)
 
Sint32 CRM64Pro::ImageObj::getColorMod (Uint8 &iR, Uint8 &iG, Uint8 &iB)
 
Sint32 CRM64Pro::ImageObj::setColorKey (Sint16 iR=-1, Sint16 iG=-1, Sint16 iB=-1)
 
Sint32 CRM64Pro::ImageObj::getColorKey (Sint16 &iR, Sint16 &iG, Sint16 &iB)
 
SDL_Surface * CRM64Pro::ImageObj::getSurface ()
 
Sint32 CRM64Pro::ImageObj::findTex (Sint32 &iIndex, SDL_Texture *&pTex, Sint32 &idScreen)
 
Sint32 CRM64Pro::ImageObj::saveToBMP (const string &sFile="")
 
Sint32 CRM64Pro::ImageObj::saveToPNG (const string &sFile="")
 
Sint32 CRM64Pro::ImageObj::save (const string &sFileCDC)
 
Sint32 CRM64Pro::ImageObj::save (Sint32 idCDC)
 
Sint32 CRM64Pro::ImageMgr::info (Sint32 idImg=0)
 
Sint32 CRM64Pro::ImageMgr::create (const string &sName, Uint32 iVersion=10)
 
Sint32 CRM64Pro::ImageMgr::close (Sint32 idImg)
 
Sint32 CRM64Pro::ImageMgr::getNum ()
 
Sint32 CRM64Pro::ImageMgr::setName (Sint32 idImg, const string &sName)
 
Sint32 CRM64Pro::ImageMgr::closeEx (Sint32 idImg, Uint32 iOwner)
 
ImageObj * CRM64Pro::ImageMgr::get (Sint32 idImg)
 
Sint32 CRM64Pro::ImageMgr::duplicate (Sint32 idImg, const string &sName)
 
Sint32 CRM64Pro::ImageMgr::child (Sint32 idImg)
 
Sint32 CRM64Pro::ImageMgr::isBMP (const string &sFile)
 
Sint32 CRM64Pro::ImageMgr::isPNG (const string &sFile)
 
Sint32 CRM64Pro::ImageMgr::loadFromFile (const string &sFile, const string &sName="")
 
Sint32 CRM64Pro::ImageMgr::load (const string &sFileCDC, const string &sName)
 
Sint32 CRM64Pro::ImageMgr::load (const Sint32 idCDC, const string &sName)
 
Sint32 CRM64Pro::ImageMgr::load (void *pBuffer, Sint32 iSize, const string &sName)
 
Sint32 CRM64Pro::ImageMgr::remove (Sint32 idCDC, const string &sName)
 

Detailed Description

The Image Manager is the unified base for the rest of important graphics modules.
It supports BMP and PNG external files although can also use a SDL_Surface.
Once the image is created, it can be saved to a CDC file (as of now, we are using CDC v1.x specification) which can be loaded in the future.

The image has the following elements:


There are some filters that can be applied to the images (it will affect the source surface and all textures):


There are four image types:


The images can be rendered to any valid screen or another image using:

CRM64Pro_Image.png


This is an advance "cloning" manager: when loading from a CDC file an image which is already loaded/created (using the name as the key), it will create a new "clone"(child) for the image. Only a single instance of the Image Manager exists which is created once Main is instantiated.
You can get a reference to this manager using Main::IImageMgr() method.

Note
The Image Manager is automatically released when Main::Terminate() is called.
At this time, if any resource is still loaded, it will be released avoding a resource leak.

Enumeration Type Documentation

Image filters.

Enumerator
IF_NOISE 

'eFilter' parameter in ImageObj::applyFilter. Apply a noise effect with a specific iValue (from 0 to 100).

IF_BLUR 

'eFilter' parameter in ImageObj::applyFilter. Apply a blur effect with a specific iValue (from 0 to 100).

IF_NEGATIVE 

'eFilter' parameter in ImageObj::applyFilter. Apply a negative effect.

IF_GREY 

'eFilter' parameter in ImageObj::applyFilter. Apply a grey effect.

IF_BW 

'eFilter' parameter in ImageObj::applyFilter. Apply a black/white effect.

IF_WIGGLE 

'eFilter' parameter in ImageObj::applyFilter. Apply a wiggle effect that can be animated using variable iValue.

IF_PIXELATE 

'eFilter' parameter in ImageObj::applyFilter. Apply a pixelate effect that can be animated using variable iValue.

Function Documentation

Sint32 CRM64Pro::ImageObj::info ( Sint32  iMode = 0)

Request Image object information.

For displaying the information, it uses the default log.

Parameters
iModeunused for the time being.
Returns
0 on success or a negative error code on failure.
Sint32 CRM64Pro::ImageObj::getName ( string &  sName)

Get the name.

Parameters
sNamea string pointer to be filled in with the image name.
Returns
0 on success or a negative error code on failure.
Uint32 CRM64Pro::ImageObj::getID ( )

Get the ID.

Returns
the object ID.
Sint32 CRM64Pro::ImageObj::assignSurface ( SDL_Surface *  pSurf,
Sint32  iOwnership = 0 
)

Assign a SDL_Surface to this image.

It is used for loading the source surface to images created with ImageMgr::create().

Parameters
pSurfSDL_Surface pointer.
iOwnership0 for creating an internal copy of the surface(the one passed to this method can be safetely removed) or any other integer for taking the ownership of the surface(the surface must not be removed if the call to this method return a success code).
By default it is set to 0.
Returns
0 on success or a negative error code on failure.
Note
Once the image has a source surface, it can not be replaced so this method will fail.
Sint32 CRM64Pro::ImageObj::setOwner ( Sint32  iOwner)

Set the owner of this image.

Parameters
iOwnerOwner of the image.
Returns
0 on success or a negative error code on failure.
Note
Only images that belongs to ImageMgr can modify its owner.
Sint32 CRM64Pro::ImageObj::getOwner ( )

Get the owner of this image.

Returns
The owner or this image.
Sint32 CRM64Pro::ImageObj::optimize ( Sint32  idScreen = 0)

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

Parameters
idScreena valid screen handle used for convert the loaded image to the same format as the screen.
The screen must be initialized.
Returns
0 on success or a negative error code on failure.
Sint32 CRM64Pro::ImageObj::rebuild ( )

Rebuild the current textures.

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
0 on success or a negative error code on failure.
Sint32 CRM64Pro::ImageObj::render ( Sint32  idRes = 0,
SDL_Rect *  rSrc = nullptr,
SDL_Rect *  rDst = nullptr 
)

Render the image to the screen.

Parameters
idResa valid screen or image handle.
By default it tries to use the default screen.
rSrcthe source SDL_Rect structure or nullptr for the entire image.
By default, it is set to nullptr.
rDstthe destination SDL_Rect structure or nullptr for rendering the image matching the rSrc.
It can stretch or shrink the image.
By default, it is set to 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.
Sint32 CRM64Pro::ImageObj::renderEx ( const double  dAngle,
const SDL_Point *  poCenter = nullptr,
const SDL_RendererFlip  rf = SDL_FLIP_NONE,
Sint32  idRes = 0,
SDL_Rect *  rSrc = nullptr,
SDL_Rect *  rDst = nullptr 
)

Render the image to the screen with extended attributes: can rotate and flipping the image.

Parameters
dAnglean angle in degrees that indicates the rotation that will be applied.
poCenterSDL_Point pointer indicating the point around which the image will be rotated.
By default, it is set to nullptr and the rotation will be done around rDst.w/2 and rDst.h/2.
rfSDL_RendererFlip value stating which flipping actions should be performed.
idResa valid screen or image handle.
By default it tries to use the default screen.
rSrcthe source SDL_Rect structure or nullptr for the entire image.
By default, it is set to nullptr.
rDstthe destination SDL_Rect structure or nullptr for rendering the image matching the rSrc.
It can stretch or shrink the image.
By default, it is set to 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 with extended attributes will not update the source surface, it will just perform a plain blit without these attributes.
Sint32 CRM64Pro::ImageObj::applyFilter ( eImageFilter  eFilter,
Sint32  iValue = 0 
)

Apply a filter to this image.

Works on stand-alone and parents images, children can not apply a filter.
As the image is shared between parent and children, applying a filter to a parent image will affect all the children ones.

Parameters
eFilterCheck eImageFilter enum for further information.
iValueadjustable value for some filters.
Returns
0 on success or a negative error code on failure.
Note
Applying a filter once a texture is created for a screen, will force a rebuilding process which is slow.
Sint32 CRM64Pro::ImageObj::setBlendMode ( SDL_BlendMode  bmValue)

Set blend mode used for rendering this image.

Parameters
bmValueSDL_BlendMode.
Returns
0 on success or a negative error code on failure.
Note
Alpha modulation and ColorKey attributes require a blending mode.
This method will enable or disable a blending mode independently of if alpha modulation and/or colorkey are in use.
SDL_BlendMode CRM64Pro::ImageObj::getBlendMode ( )

Get blend mode used for rendering this image.

Returns
SDL_BlendMode.
Sint32 CRM64Pro::ImageObj::setAlphaMod ( Uint8  iAlpha)

Set alpha modulation used for rendering this image.

Parameters
iAlphaIt ranges from 255 (opaque) to 0 (fully transparent).
Returns
0 on success or a negative error code on failure.
Note
Alpha modulation needs a blending mode, if it is already set, will not be modified, otherwise, SDL_BLENDMODE_BLEND is set.
Uint8 CRM64Pro::ImageObj::getAlphaMod ( )

Get alpha modulation used for rendering this image.

Returns
It ranges from 255 (opaque) to 0 (fully transparent).
Sint32 CRM64Pro::ImageObj::setColorMod ( Uint8  iR,
Uint8  iG,
Uint8  iB 
)

Set color modulation used for rendering this image.

By default, all components are set to 255.

Parameters
iRred color component value from 0 to 255.
iGgreen color component value from 0 to 255.
iBblue color component value from 0 to 255.
Returns
0 on success or a negative error code on failure.
Sint32 CRM64Pro::ImageObj::getColorMod ( Uint8 &  iR,
Uint8 &  iG,
Uint8 &  iB 
)

Get color modulation used for rendering this image.

Parameters
iRred color component value from 0 to 255.
iGgreen color component value from 0 to 255.
iBblue color component value from 0 to 255.
Returns
0 on success or a negative error code on failure.
Sint32 CRM64Pro::ImageObj::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, it is emulated using blending modes, if it is already set, will not be modified, otherwise, SDL_BLENDMODE_BLEND is set.

Parameters
iRred color component value from 0 to 255.
A negative value will disable the colorkey.
iGgreen color component value from 0 to 255.
A negative value will disable the colorkey.
iBblue color component value from 0 to 255.
A negative value will disable the colorkey.
Returns
0 on success or a negative error code on failure.
Note
Modifying the colorkey once any texture is created, will automatically call to rebuild() method which is slow.
Sint32 CRM64Pro::ImageObj::getColorKey ( Sint16 &  iR,
Sint16 &  iG,
Sint16 &  iB 
)

Get colorkey used for rendering this image.

Parameters
iRred color component value from 0 to 255.
A negative value set the colorkey is disabled.
iGgreen color component value from 0 to 255.
A negative value set the colorkey is disabled.
iBblue color component value from 0 to 255.
A negative value set the colorkey is disabled.
Returns
0 on success or a negative error code on failure.
SDL_Surface * CRM64Pro::ImageObj::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.
Sint32 CRM64Pro::ImageObj::findTex ( Sint32 &  iIndex,
SDL_Texture *&  pTex,
Sint32 &  idScreen 
)

Get the texture for each screen of this image.

Parameters
iIndexpointer to an integer containing 0 for find the first texture or the iIndex value of previous calls to this method.
pTexpointer to a SDL_Texture, nullptr when no texture is present.
idScreenpointer 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.
Sint32 CRM64Pro::ImageObj::saveToBMP ( const string &  sFile = "")

Export the image to a BMP file.

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

Parameters
sFilestring containing the [directory]+filename+[extension].
Ideally, it should have the .bmp extension.
Directory separators '\' and '/' are supported.
Returns
0 on success or a negative error code on failure.
Sint32 CRM64Pro::ImageObj::saveToPNG ( const string &  sFile = "")

Save the image to an external PNG file.

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

Parameters
sFilestring containing the [directory]+filename+[extension].
Ideally, it should have the .png extension.
Directory separators '\' and '/' are supported.
Returns
0 on success or a negative error code on failure.
Sint32 CRM64Pro::ImageObj::save ( const string &  sFileCDC)

Save the image to a CDC file.

Parameters
sFileCDCstring containing the [directory]+filename+[extension].
Directory separators '\' and '/' are supported.
Returns
0 on success or a negative error code on failure.
Note
If the image already exists, it will be overwritten.
Can not save child images.
Sint32 CRM64Pro::ImageObj::save ( Sint32  idCDC)

Save the image to a CDC file.

Parameters
idCDCCDC id.
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 will call the save method of its parent.
Sint32 CRM64Pro::ImageMgr::info ( Sint32  iMode = 0)

Request Image Manager information.

For displaying the information, it uses the default log.

Parameters
iMode-1 for displaying only Manager information.
0 for displaying Manager and all Objects information. This is the default value.
idImage for displaying Manager and given Image id information.
Returns
0 on success or a negative error code on failure.
Sint32 CRM64Pro::ImageMgr::create ( const string &  sName,
Uint32  iVersion = 10 
)

Creates a new image.

This method will create an empty image (no source surface assigned), use ImageObj::assignSurface() method for assigning the source surface.

Parameters
sNameThe name to give to the image e.g. 'myImage'.
The object name must be unique and with a maximum size of 64 characters or will be truncated.
The name can not start with the reserved character '#'.
iVersionImage version. 10 means 1.0 which is the only version supported (as of now).
v1.0 is set by default.
Returns
greater than 0 on success(the Image id) or a negative error code on failure.
Note
If the provided name already exists, it does nothing and return an error code.
Sint32 CRM64Pro::ImageMgr::close ( Sint32  idImg)

Close and destroy an image.

This method can only close images that belongs to the default owner (ImageMgr).

Parameters
idImg0 for closing all images or the Image id.
Stand-alone and child images can be closed but parent ones, can not as they have at least one dependency(a child).
Returns
0 on success or a negative error code on failure.
Note
If you forget to close an Image, it will be automatically closed once the GDK is terminated.
Sint32 CRM64Pro::ImageMgr::getNum ( )

Get number of loaded objects.

Returns
the number of images.
Sint32 CRM64Pro::ImageMgr::setName ( Sint32  idImg,
const string &  sName 
)

Change the object name.

Parameters
idImgImage id.
sNameThe name to give to the image e.g. 'myImage'.
The object name must be unique and with a maximum size of 64 characters or will be truncated.
The name can not start with the reserved character '#'.
Returns
0 on success or a negative error code on failure.
Sint32 CRM64Pro::ImageMgr::closeEx ( Sint32  idImg,
Uint32  iOwner 
)

Close and destroy an image.

This method can close images that belongs to any owner but as a security check, the owner must be provided.

Parameters
idImg0 for closing all images or the Image id.
Stand-alone and child images can be closed but parent ones, can not as they have at least one dependency(a child).
iOwnerOwner of the image.
Returns
0 on success or a negative error code on failure.
Note
If you forget to close an Image, it will be automatically closed once the GDK is terminated.
ImageObj * CRM64Pro::ImageMgr::get ( Sint32  idImg)

Get a pointer to the image using its handler.

Parameters
idImgImage id.
Returns
nullptr the image was not found.
A pointer to the image object.
Sint32 CRM64Pro::ImageMgr::duplicate ( Sint32  idImg,
const string &  sName 
)

Duplicate an image creating a new, identical and independent one.

Parameters
idImgImage id to be duplicated.
sNameThe name to give to the image e.g. 'myImage'.
The object name must be unique and with a maximum size of 64 characters or will be truncated.
The name can not start with the reserved character '#'.
Returns
greater than 0 on success(the Image id) or a negative error code on failure.
Note
If the provided name already exists, it does nothing and return an error code.
The new image will not be optimized for any screen, you can call ImageObj::optimize() method for doing it.
Sint32 CRM64Pro::ImageMgr::child ( Sint32  idImg)

Create a child image dependant on the provided one(the parent).

A child image uses the source surface and textures for the screens of its parent but can have different attributes. It is useful for saving memory.

Parameters
idImgparent Image id.
If the provided image is a child, internally it will redirect this request to the parent in order to create the new child.
Returns
greater than 0 on success(the Image id) or a negative error code on failure.
Note
The child use the parent's name.
Sint32 CRM64Pro::ImageMgr::isBMP ( const string &  sFile)

Check if the file is a BMP.

Parameters
sFilestring containing the [directory]+filename+[extension].
Directory separators '\' and '/' are supported.
Returns
0 on success(it is a BMP) or a negative error code on failure.
Sint32 CRM64Pro::ImageMgr::isPNG ( const string &  sFile)

Check if the file is a PNG.

Parameters
sFilestring containing the [directory]+filename+[extension].
Directory separators '\' and '/' are supported.
Returns
0 on success(it is a PNG) or a negative error code on failure.
Sint32 CRM64Pro::ImageMgr::loadFromFile ( const string &  sFile,
const string &  sName = "" 
)

Load an image (BMP or PNG formats).

Parameters
sFilestring containing the [directory]+filename+[extension].
Directory separators '\' and '/' are supported.
sNamethe image object name.
By default, it is set to empty to use the filename (without extension) for setting the image object name.
The object name must be unique and with a maximum size of 64 characters or will be truncated.
Returns
greater than 0 on success(the Image id) or a negative error code on failure.
Sint32 CRM64Pro::ImageMgr::load ( const string &  sFileCDC,
const string &  sName 
)

Load an image stored in a CDC file.

Parameters
sFileCDCstring containing the [directory]+filename+[extension].
Directory separators '\' and '/' are supported.
sNamestring with the image name (maximum size of 64 characters).
If the Image is already created, this method will call child() for creating a child.
Returns
greater than 0 on success(the Image id) or a negative error code on failure.
Sint32 CRM64Pro::ImageMgr::load ( const Sint32  idCDC,
const string &  sName 
)

Load an image stored in a CDC file.

Parameters
idCDCCDC id.
sNamestring with the image name (maximum size of 64 characters).
If the Image is already created, this method will call child() for creating a child.
Returns
greater than 0 on success(the Image id) or a negative error code on failure.
Sint32 CRM64Pro::ImageMgr::load ( void *  pBuffer,
Sint32  iSize,
const string &  sName 
)

Load an image (BMP or PNG formats) stored on a memory buffer.

Parameters
pBufferbuffer pointer containing the BMP or PNG raw data.
iSizesize in bytes of the buffer.
sNamethe image object name.
The object name must be unique and with a maximum size of 64 characters or will be truncated.
Returns
greater than 0 on success(the Image id) or a negative error code on failure.
Sint32 CRM64Pro::ImageMgr::remove ( Sint32  idCDC,
const string &  sName 
)

Remove an image stored in a CDC file.

Parameters
idCDCCDC id.
sNamestring with the image name (maximum size of 64 characters).
Returns
greater than 0 on success or a negative error code on failure.
Note
The image must be closed before trying to remove it from the CDC.