Overview

The Mobile Dragon 2D API gives you the set of functions and classes for drawing 2D scenes. The 2D API is capable to draw points and lines primitives, 2d sprites, play 2d animation, display tile maps. The API is developed to work with DragonTool exported 2d sprite graphics data files.

Render2D

Render2D class is the main class responsible for drawing 2d scenes. This class provides methods necessary for drawing points and lines primitives and sprites. It also manages images loading. An instance of the Rended2D class must present in every MobileDragon 2d application.
Create Render2D instance in your MDGame derived class constructor and assign it’s pointer to render2d member of System class instance. For example:

GameProject::GameProject(System* system_)
{
// Remember System object pointer.
system = system_;

// Create Render2D class instance and save it's addreess
// pointer in Sysem object instance.
system->render2d = render = new Render2D;
}

Let’s take up with general Render2D features:

Clearing the backbuffer:

// Define clear color.
render->SetClearColor(Color(0,0,128,0));

// Clearing color backbuffer.
render->Clear(Render2D_Clear_Color);

Determine screen dimensions:

Render2D provides a way to determine screen dimensions.
For example:

// Get screen width.
Fixed screen_width = render->GetScreenWidth();

// Get screen height.
Fixed screen_height = render->GetScreenHeight();

Working with viewport and display origin:

You can specify the rectangle “viewport” area on the device screen. All drawings will be
clipped to this viewport area.
For example:

// Set render viewport to top half of display area.
render->SetViewport(0,0, screen_width, screen_height / 2);

or

Rectangle vp_rect(0, 0, screen_width, screen_height / 2);
render->SetViewport( vp_rect );

Also you can determine and specify viewport origin in global coordinates:

// Determine current vieport origin.
Int origin_x, origin_y;
render->GetOrigin( &origin_x, &origin_y );

// Move origin 50 points down and 60 points left.
render->SetOrigin( origin_x + 50, origin_y - 60 );

or

render->MoveOrigin( 50, -60 );

Scaling:

You can specify scaling factor for viewport drawing operations:

// Determine current scaling factor.
Fixed x_scale,y_scale;
render->GetScale( &x_scale, &y_scale );

// Doble the scaling factor.
render->SetScale( x_scale * 2, y_scale * 2);

Transparency:

You can specify alpha transparency value for all subsequent drawing operations:

// Get current transparency settings.
Byte alpha = render->GetAlpha();

// Set transparency to 50%.
render->SetAlpha( 128 );

Gamma correction:

Render2D provides methods to perform gamma correction. Two methods are provided:
GetColorGamma() to retrieve current gamma correction value, and SetColorGamma()
to set new gamma corretion level. Gamma correction value ranges from 0 ( total darknesss) to 2 (maximum brightness).

/// Get color gamma level.
Fixed gamma = render->GetColorGamma();

/// Set new color gamma level.
render->SetColorGamma( 1.5 );

Drawing:

Render2D provides methods for drawing points and lines primitives:

// Draw green point at position 5 , 5.
render->DrawPoint( 5, 5, Color( 0, 255, 0 ) );

// Draw red line from screen top-left corner to bottom-right corner.
render->DrawLine( 0, 0, screen_width, screen_height, Color( 0, 255, 0 ) );

All drawing operation are queued. To actually perform drawing call Render2D Flush() method. This draws all sprites and primitives to backbuffer.

// sort draw queue by z order and draw it.
render->Flush();

And to copy backbuffer to device display memory call Render2D Show() method:

// Copy backbuffer to display video memory.
render->Show();

Image

Image class is used to hold .pcx images loaded from PackDir file.

Only PCX 256 palette graphics format supported of square size with power of two – side length (8x8, 16x16, 32x32, 64x64, 128x128 and 256x256). Image can have transparent pixels. Pixels with value R=255, G=0, B=255 are always transparent and not drawn.

Image alpha channel can be stored in file with the same name and added “+a” suffix. To store alpha values in PCX file format you need to copy pixel alpha channel value into it’s RGB components values then save new image as PCX 256 palette graphics format. Such a file will be automatically loaded into image alpha channel. ( for example if You have rgb bits of image stored in “test.pcx” file than alpha channel will be loaded from file "test+a.pcx" ).

Load images using Render2D::LoadImage() method.
For example:

// Find specified image by ASCII name in
ObjRef<Image> img_test = render2d->LoadImage( “test” );

When this image is not needed any more – free occupied resources like this:

img_test = NULL;
render2d->UpdateResources();

Sprite2D

Sprite2D represents rectangular area of Image. Let’s for example define Sprite2D object referencing area from point (10, 10) with width 20 and height 16.

// Init sprite referencing to image rectanglular area from point (10, 10)
// with width = 20 and height = 16.
Sprite2D spr_test;
spr_test.Init( img_test, 10, 10, 20, 16 );

To draw sprites use SpriteTransform class that holds Sprite2D rendering transformation.

SpriteTransform

SpriteTransform class objects are used to hold Sprite2D rendering transformations. Possible transformations include: position translation, scaling, rotation, applying alpha transparency, visibility flag.
For example:

// Let's draw created sprite at position (50, 100) with 50% transparency,
// rotated 45 degress, and scaled to it's double size.

// Create SpriteTransform object.
SpriteTransform st_test;

// Bind created sprite to it.
st_test.Set( spr_test );

// Position translation x = 50, y = 100
st_test.Translate( 50, 100 );

// Choose 50% alpha
st_test.SetAlpha( 128 );

// Rotated 45 degrees
st_test.SetAngle( 45 );

// Scaled by 2 ( width and height )
st_test.SetScale( 2, 2 );

// Update transformation.
st_test.Update();

// Draw it.
render2d->Draw( st_test );

Animation

MobileDragon provides support for playing 2d sprite animation. Animation is represented as an array of SpriteTransform objects pointers. In general, you use animations loaded from GameData resource (see GameData class description for more details).

SpriteTransform class has member functions GetTime(). GetTime() returns current frame animation delay. Actor2D class object can be used to control (“play”) animation.

For example:

// Load the animation somewhere.
SpriteTransform **anim = LoadAnimation();

// Actor2d object instance.
Actor2D actor;

// Bind actor object to this animation and choose infinite playback.
actor.Set( anim, True );

// Advance animation time by 30 “points”.
actor.Play( 30 );

// Draw animation frame. GetFrame() returns pointer to
// current frame SpriteTransform.
render->Draw( actor.GetFrame() );

Font2D

Font2D class provides ability to display text messages. Font2D character glyphs loaded from binary file <Name>.bin and <Name>.pcx. These files can be prepared with TextureFont utility.
Init Font2D class object like this:

// Font2D object instance.
Font2D font;

// Load game font.
font.Create( render, "arial_black" );

And to display sample message:

// Display message.
font.Draw("sample message", 10, 10 );

GameData

MobileDragon comes with tool named DragonTool – program to edit 2d games graphics resources. These resources include sprite collections, tile maps and animations. DragonTool exports projects to one ore more *.pcx files and one *.dt binary file. These files must be kept together when composing game resource PackDir image.

GameData class is used to load and manage DragonTool prepared resource.

// Instance of GameData object.
GameData gd;

// Vector of SpriteTransform pointers to hold sprite collection.
vector<SpriteTransform*> palette;

// SVector of SpriteTransform objects to hold actual SpriteTransform
// objects.
SVector<SpriteTransform> st_table;

// Vectors to hold node CustomData attributes.
vector<Char*> tokens;
SVector<CustomData>* cd_table;

// TileMap object to load.
TileMap floor;

// Load GameData resource named “set1_1”.
gd.Init( render, "set1_l" );

GameData structure is the same tree structure seen in DragonTool outline. After loading the resource we can walk the tree and load variuos node items. At the beginning current node is the root node.
The first thing to do is to enter that node:

// Enter the root node.
gd.EnterNode();

Then go to sprite collection node named “palette”. This is dummy node with Sprites linked as child nodes to it. It holds sprite palette for our indexed tile map.

// Step to “palette” node.
gd.GoToNextByNameNode("palette");

// Export palette node.
gd.ExportNode( & palette, & st_table, & cd_table, tokens.begin() );

Then let’s load the tile map itself. That tile map resides in node “level10/floor”

// Go to top node in this level.
gd.GoToTopNode();

// Goto node “level10” and enter it.
gd.GoToNextByNameNode("level0");
gd.EnterNode();

// Go to tile map node “floor”.
gd.GoToNextByNameNode("floor");

// And export it to TileMap object.
gd.ExportNode( &floor );

// Set palette for this tile map. And set tile map cell size.
floor.SetPalette( &tile_map_palette );
floor.SetCellSize(24, 24);

Let’s for example load animations from node “/animation”:

// Animation class instance to hold node animations.
Animation anim_node;

// Go to root node.
gd.GoToRootNode();

// Enter root node.
gd.EnterNode();

// Go to “animation” node.
gd.GoToNextByNameNode("animation");

// Export node animations to anims object.
anim_node.ExportNode( & gd, st_table, cd_table, tokens.begin() );

// Get individual animations from node.
SpriteTransform ** anims[ 2 ];

// Get animation “walk-face”.
anims[0] = anim_node.Find( "walk-face" );

// Get animation “walk-right”.
anims[1] = anim_node.Find( "walk-right" );

Copyright 2005-2006 Herocraft Hitech Co. Ltd.