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

Loading...
Searching...
No Matches
Image
Graphics modules

## 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 module 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::imageMgr()

Note
  The Image Manager is a singleton, automatically created once Main is instantiated. You can get a reference to this manager using Main::imageMgr() 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 : Sint32 { 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 : Sint32

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.