Architecture:Gfx Module

The graphics module provides the basic functionality for those modules that need to draw something onto the screen, like the GUI and Map modules. It is an abstraction layer on top of whatever media library will be used.

Surfaces

A surface provides a canvas to draw upon. It is a pure virtual class that needs to be implemented in terms of the used media library. As such, surfaces can not be instantiated directly. Instead, the global function gfx::create_surface() returns a new surface instance, depending on the dynamically loaded gfx backend. The image class is a thin wrapper around a surface that takes care of instantiating the underlying surface.

Adonthell supports both RGB and RGBA surfaces. The former can have a color that will be transparent and a per-surface alpha value. Latter has an additional alpha channel to support per-pixel alpha. Once a surface is created, it can be filled with data by drawing to it, or by loading an image file in PNG format. Only PNG images in truecolor format (with or without alpha channel) are supported right now.

Since the same image might be used multiple times, a cache exists that should be used to store all loaded images. It uses a reference count to keep track of image usage, although it will not automatically discard unused images. Instead, it has a configurable size and will only start deleting images no longer referenced once this size limit is reached. All unused images can be purged manually at any time though. The simplest way to store an image in the cache is to use the global gfx::surface_cache() function, which creates a surface, loads a PNG and puts it into the cache before returning a pointer to the image.

The screen encapsulates a special surface that represents what is displayed to the user. It can be acquired with a call to screen::get_surface(). Since it is double buffered, a separate call to screen::update() will be necessary to blit the current screen contents to video memory.

Sprites

A sprite in terms of Adonthell describes a graphical object capable of containing multiple states, where each state is represented by a sequence of one or more images (aka animation). In general, there is no limit to the number and type of states that a sprite can have, although conventions in other parts of the Adonthell engine might require that sprites representing certain objects (i.e. characters) have to have certain states. On top of these mandatory states, individual sprites can have additional states for special purposes. These will usually be triggered by Python scripts.

The animations representing individual states of a sprite are composed of multiple frames (each of which is a surface) and a delay to the next frame. While an animation is playing, a callback is registered with the event system that will be notified when it is time to switch to the next frame. Since the resolution of time events is not very fine grained (~ 1 tick every 125ms), really short delays between frames are not possible. (Something that might be worth changing, if it becomes an issue).

Sprites are implemented by the animation class and persisted in the sprite format described separately.