Image

Description

Image Manager and Image objects for handling surfaces and textures [v26.01.0].

Overview

The Image module provides unified management for images and textures used by all graphic modules in the GDK. It supports BMP and PNG external files as well as SDL_Surface sources. Images can be saved to and loaded from CDC archives (using CDC v1.x specification).

Key features

• Unified handling: Single interface for all graphic modules' image needs
• Multiple formats: Support for BMP, PNG external files and SDL_Surface
• Multi-screen textures: Automatic texture creation per screen
• Image filters: Built-in visual effects (noise, blur, negative, etc.)
• CDC storage: Load and save images using CDC v1.x specification
• Cloning support: Efficient resource sharing through parent-child relationships

Image elements

Source surface	Standard SDL_Surface where the imported BMP, PNG or SDL_Surface is stored
Textures	One texture per screen. Created "offline" via optimize() or "online" automatically on first render. Always created with SDL_TEXTUREACCESS_TARGET flag
Attributes	Color key (transparency), alpha value (surface transparency), color modulation and blending mode (SDL_BlendMode)

Image filters

The following filters can be applied to images (affects source surface and all textures):

Noise	Adds random noise effect
Blur	Applies blur/smoothing effect
Negative	Inverts color values
Grey	Converts to greyscale
Black/White	Converts to two-tone black and white
Wiggle	Applies wave distortion effect
Pixelate	Reduces resolution for pixelated effect

Image types

Uninitialized	Created with ImageMgr::create() but lacks source surface (set via Image::assignSurface()). Not usable
Stand-alone	Fully usable image with no children. No restrictions
Parent	Stand-alone image with one or more children. Restrictions: ColorKey cannot be modified, cannot be closed while children are live, name cannot be changed
Child	Uses parent's source surface, textures and name. Restrictions: ColorKey cannot be modified, save() calls parent's method, name cannot be changed

Rendering methods

Images can be rendered to any valid screen or another image:

Image::render()	Plain rendering with optional stretch or shrink
Image::renderEx()	Extended rendering with rotation around a given point and vertical/horizontal flip effects

Manager type

This is an advanced "cloning" manager: when loading an image from a CDC file that is already loaded or created (using the name as the key), it will create a new "clone" (child) for the image. Child images share the source surface and textures with their parent for memory efficiency.

Best practices

• Use optimize() to pre-create textures offline when loading screens to avoid runtime hitches
• Leverage cloning to efficiently share image resources across multiple game objects
• Be aware of parent-child restrictions when designing your image management strategy
• Use PNG format for images requiring transparency; use BMP for simpler opaque images
• Apply filters sparingly as they affect both source surface and all textures
• Use render() for simple cases and renderEx() only when rotation or flipping is needed
• Remember that child images cannot modify ColorKey, set it on the parent before creating children
• Access the manager exclusively through Main::IImageMgr()

Note

The Image Manager is a singleton, automatically created once Main is instantiated. You can get a reference to this manager using Main::IImageMgr() method.
The Image Manager is automatically released when Main::Terminate() is called. At this time, any resource still loaded will be released, avoiding resource leaks.

Classes
class	CRM64Pro::Image
	Image Object class. More...
class	CRM64Pro::ImageMgr
	Image Manager class. More...

Enumerations
enum	CRM64Pro::eImageFilter {   CRM64Pro::IF_NOISE = 1 , CRM64Pro::IF_BLUR = 2 , CRM64Pro::IF_NEGATIVE = 3 , CRM64Pro::IF_GREY = 4 ,   CRM64Pro::IF_BW = 5 , CRM64Pro::IF_WIGGLE = 6 , CRM64Pro::IF_PIXELATE = 7 }
	Image filters. More...

Enumeration Type Documentation

eImageFilter

enum CRM64Pro::eImageFilter

Image filters.

Enumerator
IF_NOISE	'eFilter' parameter in Image::applyFilter. Apply a noise effect with a specific iValue (from 0 to 100).
IF_BLUR	'eFilter' parameter in Image::applyFilter. Apply a blur effect with a specific iValue (from 0 to 100).
IF_NEGATIVE	'eFilter' parameter in Image::applyFilter. Apply a negative effect.
IF_GREY	'eFilter' parameter in Image::applyFilter. Apply a grey effect.
IF_BW	'eFilter' parameter in Image::applyFilter. Apply a black/white effect.
IF_WIGGLE	'eFilter' parameter in Image::applyFilter. Apply a wiggle effect that can be animated using variable iValue.
IF_PIXELATE	'eFilter' parameter in Image::applyFilter. Apply a pixelate effect that can be animated using variable iValue.