GAPIDRAW FEATURES

The Software Blitter

The software blitter in GapiDraw has been designed from the ground up based on the following three principles:

1. Expandable. It should be easy and manageable to add new features to current blit operations, without adding extreme bloats of source code as a result. GapiDraw uses a programming technique called Template Meta Programming in C++ which makes the source code both easy to expand as well as very high in performance. Several customers that have bought source code licenses of GapiDraw have expressed great satisfaction with the design of the modular graphic core of GapiDraw.
    
   

2. FirePower - Onrush by ManaiSoft. Made with GapiDraw.

   High Performance. For example, many images in GapiDraw are stored in something that is called a surface, a 16-bit image format. Since all processors today can operate on 32 bits of information at the same speed as they operate on 16 bits, all pixel routines in GapiDraw are fine tuned to always operate on 32 bits of information. As an example, drawing surfaces with opacity will only require one multiplication per pixel since even the multiplication can operate on multiple pixels thanks to some clever bit shifts and 32-bit logic!
    
   
3. Native Orientation Rendering. Every display has a frame buffer stored in RAM. When you read a byte from the frame buffer, the cache in the device will automatically pre-fetch the next couple of bytes in the background. To take advantage of this, every single graphics loop in GapiDraw always operates in a cache-optimized way so that if many pixels are to be read from the frame buffer, most of them will be read from the processor cache. If you think of this for a while, given that you can draw to the display in any possible orientation (rotated left, right or upside down), it becomes quite a big task to realize this for yourself in a stable and performance efficient way. Using GapiDraw you can focus on the content, not on optimizing the rendering performance when your application is drawn rotated to the left.

Surfaces

Jack the Uni-Psycle by Discord Studios. Made with GapiDraw.

A surface is an image area which you can draw upon. You can also copy other surfaces to this image area, or access it directly for custom pixel effects.

In GapiDraw, even the display and the back buffer are two surfaces. Thus, to draw to the back buffer, you typically create a new surface, load an image into that surface, and draw it onto different positions on the back buffer to simulate movement.

GapiDraw supports three types of surfaces: opaque surfaces, surfaces with 1-bit transparent mask (like GIF images), and surfaces with variable alpha (like PNG images) - called RGBA surfaces. RGBA surfaces are used for all Windows Vista graphics, and is also used for all graphics on the popular iPhone and iPod Touch handheld devices.

Zero-Overhead Image Loading

Memory on handheld computers is precious and should be used as sparsely as possible. Many legacy applications use the image loading routines from Virtual Office Systems that provide a direct link to the system built-in image decoders to load PNG, JPG, GIF and BMP images from a file, resource or memory. The built-in image decoders however have one significant drawback: they use huge amounts of memory!

To give an example. A typical game stores pictures as PNG images on disk. The images are 8-bit indexed color, and the final decompressed image should be stored as a 16-bit image in a format combatible with the display. The amount of memory required when using the built-in image decoding routines are a (1) the size of the file as loaded into memory (this can be minimized by using memory mapped files), (2) the size of the file as expanded to 24-bit true color (which is necessary since the built-in routines does not expand to the 565 display format on all devices), and (3) the size of the final 16-bit surface. Given an image that is 2000x1000 pixels, the minimum amount of memory required to load the bitmap is (2000x1000x24bit + 2000x1000x16bit) = 9,77 mb using the system built-in image decoder.

GapiDraw includes custom-written PNG and BMP image decoders with nearly zero memory overhead! Loading an image of 2000x1000 pixels will only require 3.91 mb using GapiDraw's proprietary image decoder (~2.5 times less memory)!

Template Meta Programming

Internally, GapiDraw uses an optimization technique called template meta programming. Template meta programming is a C++ programming technique that allows optimizations such as loop-expansion and automatic means of creating temporary variables in optimized code. Template meta programming is a fairly recently introduced technique, and has previously been used in class libraries such as Blitz++. GapiDraw uses the template meta programming technique for loop-expansion.

In most graphics operations, GapiDraw accepts several flag parameters that changes how pixels are to be copied between surfaces. Examples are transparency, color masks and colorizations. Implementing support for three flags, a developer can write either one loop that covers all flags or eight individually optimized loops. Writing eight different loops for three flags means having to write another additional eight loops if a new flag is added to the API. In some operations, GapiDraw accepts up to eight flags as parameters. Writing one loop imposes significant performance issues in that all flags have to be checked for every single pixel being copied, whereas writing 256 individually optimized loops results in un-manageable source code.

GapiDraw supports multiple display formats such as 16-bit 444, 16-bit 555 and 16-bit 565. Using Template Meta Programming, all blit loops are copied by the precompiler to generate unique and optimized loops for every display configuration! The result is simply stunning performance!

Detailed Feature List

If you click on one of the orange links below you are taken straight to the GapiDraw 3.6 documentation where you can read more about the specific topic.

Application Framework for RAD development

• Proven OS integration. The application framework is centered around an easy to use, open sourced class that serves as a starting point for your application. The application frameworks takes care of every possible OS event such as minimizing due to incoming phone calls, warning signs due to low battery or other notifications. The GapiDraw framework has been improved during many years, and tested on tens of thousands of devices.
• Simple to use configuration structure to set parameters such as maximum number of frame updates per second and double click support.
• The option to set and modify the maximum number of frame updates per second (FPS). Limiting the maximum number of frame updates per second has several advantages, such as prolonging battery life. GapiDraw features an advanced timer class that adaptively analyzes the number of frames rendered each second, and spreads out the frames in a way that guarantees smooth playback during the entire update cycle.
• The option to lock all hardware keys when in full screen display mode, to prevent application switching.

Display

Mobile Device Features

• Extensive back buffer support.GapiDraw supports three different types of back buffer configurations, all of which are used today on various devices. The first type is where display access is direct, and the application itself has to manage the back buffer and copy it to the display. The other type is where the application manages the back buffer and notifies the system to update the display using the back buffer provided. The third type is where the back buffer is buffered and where the system will copy it to the display itself.
• Extensive display support. Every single blit and graphic drawing routine in GapiDraw supports 12-bit, 15-bit as well as 16-bit displays with no per-pixel conversion in the final blit to the display. Everything is rendered internally exactly as it will look on the display, which is one of the reasons GapiDraw performs so well. GapiDraw can provide support for all these display types while still performing well thanks to the Template Meta Programming technique used (see the information box to the left).

Stationary PC Features

• Hardware accelerated blits in full screen mode for high performance 2D graphics
  
• Can run in either windowed or full screen mode on stationary PCs
• Support for multithreading, separating the rendering thread from the UI thread for seamless graphics rendering while moving windows. GapiDraw ships with two copies of its framework, one version uses one thread (most suitable for full screen applications) and the other two threads (more suitable for windowed applications).
• A choice to store the back buffer in either video memory or system memory in hardware accelerated full screen mode. Storing the back buffer in system memory is a good option when information has to be read from it, for example when doing some alpha blend operations not accelerated by DirectDraw.
• An option to wait for the vertical blanking period before copying the back buffer to the display for smooth graphics updates in full screen mode
• Direct throughput to DirectDraw. If you want direct access to the DirectDraw object or the primary surface, GapiDraw provides direct access to these classes if you already have legacy code you want to use.
• Hardware information access, like monitor frequency, available video memory and hardware status.
• Automatic management of lost video surfaces when switching between the Windows desktop and a full screen GapiDraw application.

Shared Features

• Object Oriented class structure - both the display class as well as the back buffer class inherits all the drawing and blitting features from the surface class, meaning you can draw and copy images to them freely.
• Draw to the display in any orientation with no performance loss. Typically, handheld computers use a portrait oriented display in a resolution such s 240 x 320 pixels. GapiDraw can use this display as either a 240 x 320 display, or a 320 x 240 display, in any orientation (0, 90, 180, 270 degrees rotation) without any performance loss due to advanced internal coordinate transformations. By default GapiDraw will use the orientation used by the operating system, this can however be overridden during startup and can also be changed at any time when the application is running - GapiDraw will then internally rotate all bitmaps to fit the new orientation for maximum performance.
• Support for creating a back buffer without a physical display attached (an "offscreen display"). This is suitable when creating graphics that will be drawn using a Device Context (DC) through GDI, or when creating high performance graphics from a DLL file.
• Coordinate transformations between device coordinates and logical coordinates, especially useful when the display has been rotated or scaled.

Surface Management

Stationary PC Features

• Create surfaces in system memory, local video memory or non local video memory
• Support for locking and unlocking surfaces stored in video memory

Shared Features

• Support for surfaces that are opaque, have 1-bit alpha or variable alpha. 1-bit alpha is realized by setting a color key to the surface, variable alpha is realized by using a surface class called RGBA surface.
• Clipping support, you can set an area that equals either the full surface or a part of the surface, and all graphics drawn to the surface will only be painted within that area. This works for all GapiDraw operations, and all GapiDraw operations have been specifically optimized for clipping. This means that there are no pixel-by-pixel checks done to see if it's "inside" the clipping area or not.
• Color key support, to set a color that will be transparent when copying images from one surface to another 
• The option to save the surface to a BMP or PNG image
• Direct access to the memory area used by the surface
• Win32 Device Context (DC) access to the surface
• Converting COLORREF values into the native format of the surface using open sourced image conversion routines

Surface Intersections

• Surface-to-surface intersection. This highly optimized routine will first perform a bounding box check of two surfaces, and then do a pixel-by-pixel scan of just the overlapping area to see where they intersected. The surface function Intersect() will even return where the surfaces intersection so you can draw appropriate effects at the right location.
• Collision mask-to-surface intersection. If you have a game like a flipper game you can set up a large collision mask surface which you can use to check if another surface like a flipper ball intersects with specific colors upon that surface to check for intersections

2D Surface Operations

• AlphaBlt to perform a copy of a surface with variable alpha to another surface. AlphaBlt supports stretching, opacity and mirroring (left/right and up/down).
• AlphaBltFast to perform a fast 1:1 copy of a surface with variable alpha to another surface. AlphaBltFast supports opacity.
• Blt to perform an opaque or a 1-bit alpha copy of a surface to another surface. Blt supports color keys, color fills, opacity, mirror (left/right, up/down, rotation, scale and stretch.
• BltFast to perform a fast 1:1 opaque or a 1-bit alpha copy of a surface to another surface. BltFast supports color keys, color fills, opacity and highly optimized "Photoshop-style" effects such as Multiply, Screen, Overlay, Hue and Colorize.

Image Loading and Saving

• Support for loading BMP, GIF, JPEG and PNG images. BMP images can be normal or RLE-encoded, GIF images can be opaque and with 1-bit alpha, PNG images can be opaque, with 1-bit alpha or with variable alpha
• Custom written BMP image loader for zero memory overhead
• Custom written PNG image loader with minimum memory overhead
• Support for loading only the transparent part of PNG images

Drawing Tools

• Pixels using GetPixel, SetPixel and SetPixels (to set many individual pixels at a high rate).
• Lines with and without opacity and anti-aliasing.
• Rectangles with and without opacity.
• Filled Rectangles with and without opacity.
• Bitmapped text that can be left, right or center-aligned. Text kerning can be individually set between characters to provide advanced typography solutions.

Font Support

• Built-in system font that can be used for debugging output. The system font comes in two options - one with a thin border and one without. The built.in system font can be re-created at any time with a custom color.
• Simple font format. Each letter is drawn exactly as wide as it is in pixels.
• Advanced font format. Each letter have individual kerning options, to make characters such as paranthesis flow smoothly with other text.
• A FontMaker application to quickly make bitmapped fonts in the advanced font format from TrueType fonts.

File and Resource Management

• GapiDraw can store resources such as images and data objects inside a Virtual File System, VFS. This file system is quite flexible, and supports files stored in folders, and the option to get direct file access using standard operations such as Read, Reset, Seek and Tell.
• A VFSEdit application to easily make zipped VFS archives using drag and drop is included.

Miscellaneous

• Mouse cursor support, including several high quality, animated bitmapped pointers with variable alpha from top artists at Debianart.