Image

Description

Image Manager and Image objects for handling surfaces and textures [v26.02.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.

Naming security

Resource names are restricted to prevent collisions with system assets. The characters '#' and '@' are reserved for internal engine use. Any attempt to create or rename a resource starting with these characters will be rejected (returning a negative error code).

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.