MAP class samples

This section shows common samples of how to create and manage DIV Games Studio graphic maps.

A MAP object is the image format used by DIV Games Studio to represents a bitmap or texture in his engine. Is basically a simple uncompressed bitmap with a palette (a PAL data). One interesting feature of the MAP format is the Control Point list.

A Control Point is a coordinate, in MAP bitmap space, that represents a "hot spot", like how works in the Windows Cursor images. This point coordinates are relatives to the image bitmap but are translated to the screen space when you draw the MAP image.

This feature helps the programmer to define the logical center of the image, used to for draw, rotate and scale operations, but also, and is the main useful usage, to easily place other objects related with the MAP position in screen (e.g. a ship engine particle or a bullet from a weapon barrel).

By default, all MAP images has a default Control Point that reference the center of the image. You can overwrite the default Control Point coordinates and create new ones as many you need, with a limit of 1000 points in total.

Note

Only the first Control Point is used as center of the image for draw, rotate and scale operations.

The MAP format also contains other data like a graph id and a description fields. The graph id is used as index to reference a MAP image. The description is an optional field used to add a little description of the image.

Note

The graph id value is not required for standalone MAP images (in this case, DIV Games Studio assigned one when you load a MAP from a file). This field value only is required when you want to store the image in a FPG file.

Create a new MAP graphic

This code shows how to create an empty 64x128 MAP instance, with a graph id and a description values. You can omit these fields to use default values:

var palette = new PAL("DIV.PAL");
var map = new MAP(palette, 64, 128, 12, "Test map.");

Load a MAP graphic

This code shows how to load an existing MAP file:

var map = new MAP("PLAYER.MAP");

Also you can load a MAP file from a byte array:

byte[] buffer = System.IO.File.ReadAllBytes("PLAYER.MAP");
var map = new MAP(buffer);

Import a supported image format

This code shows how to import a supported image file (JPEG, PNG, BMP, GIF, TGA and PCX) as MAP image. The process converts all original colors to a 8 bits (256 colors) format:

var map = MAP.FromImage("PLAYER.PNG");

Warning

PCX import feature only supports 8 bits (256 colors) PCX images. If you try to import a PCX image with other BPP format, you thrown an exception.

Converts all colors to a specific palette

When you imports a supported image file, you can also specify a PAL instance to convert the original colors to a specific colors:

var palette = new PAL("DIV.PAL");
var map = MAP.FromImage("PLAYER.PNG", palette);

Note

You can imports MAP files to apply color conversion.

Write bitmap colors

You can write a palette color index from the bitmap using the pixel index:

map[42] = 224; // Writes the color index 224 in the pixel index 42.

Also you can use the pixel coordinates to write it:

map[32, 24] = 224; // Writes the color index 224 in the pixel located in x32 y24.

If you need to write all bitmap data in one step you can use this way:

... // Creates a 64x64 MAP image.
var bitmap = new byte[64 * 64]; // Creates a 64x64 byte array.
... // Sets color indexes in each pixel.
map.SetBitmapArray(bitmap);

Note

Remember that the bitmap pixels store the color index in the assigned palette, a value from 0 to 255, instead the RGB-DAC values.

Read bitmap colors

You can read a palette color index from the bitmap using the pixel index:

byte colorIndex = map[42]; // Reads the color index from pixel index 42.

Also you can use the pixel coordinates to read it:

byte colorIndex = map[32, 24]; // Reads the color index from pixel located in x32 y24.

Also you can read each pixel using a foreach loop:

foreach (byte colorIndex in map)
{
    Console.WriteLine(colorIndex); // Prints the color index of the current pixel.
}

If you need to read all bitmap data you can use this way:

byte[] bitmap = map.GetBitmapArray();

Get the RGB texture

If you need, for example, render the bitmap in a custom tool, that works with full RGB 24/32 bits, you can get a copy of the all colors in RGB format [0..255] using a simple call:

Color[] texture = map.GetRGBTexture();

Clear all bitmap data

You can erase all bitmap data using this call. This method sets all pixels to zero, the first color of the palette (usually expected black color for transparency):

map.Clear();

Manage Control Points

The management of the Control Points list is the same as the List<T> generic class.

You can read any point using his index in the list:

ControlPoint point = map.ControlPoints[0]; // Reads the first/default control point.

Also you can read each one using a foreach loop:

foreach (ControlPoint point in map.ControlPoints)
{
    Console.WriteLine(point); // Prints the Control Point coordinates.
}

Use the Add method to add new point to the list:

map.ControlPoints.Add(new ControlPoint(16, 16)); // Adds a new Control Point in x16 y16.

Use the RemoveAt method to remove a point using his index position:

map.ControlPoints.RemoveAt(2); // Removes the third (index 2) Control Point.

And use the Clear method to remove all points:

map.ControlPoints.Clear();

Note

Don't worry if you keep empty the Control Points list. By default, if not exists any point, DIV Games Studio created a default one with the center coordinates of the bitmap.

Get or set the GraphID value

You can get or set the graph id value using the following property:

int graphId = map.GraphId;

map.GraphId = 10;

Note

This value is only required when you want to store the MAP in a FPG file. If you want to load the image from a file instead, this value is omitted and DIV Games Studio assigned one automatically. By default, this value is 1.

Warning

If you try to sets a value under 1 or over 999, you thrown an exception.

Get or set the Description value

You can get or set the description value using the following property:

string description = map.Description;

map.Description = "A simple description.";

Note

The description field has a limit of 32 characters. You can enter any string value with more of 32 characters, but when you save the MAP file, this field save only the first 32 characters. This field is optional.

Save MAP graphic to a file

You can easily save your changes to a MAP file using the following call:

map.Save("NEWMAP.MAP");