Creating and deleting images
[Images]

Image Basic routines needed to work with images. More...

Functions

UL_IMAGEulCreateImage (int width, int height, int location, int format, int palCount)
int ulCreateImagePalette (UL_IMAGE *img, int location, int palCount)
UL_IMAGEulConvertImageToPaletted (UL_IMAGE *imgOriginal, int newLocation, int newFormat)
int ulRealizeImage (UL_IMAGE *img)
int ulUnrealizeImage (UL_IMAGE *img)
void ulDeleteImage (UL_IMAGE *img)

Detailed Description

Image Basic routines needed to work with images.


Function Documentation

UL_IMAGE* ulCreateImage ( int  width,
int  height,
int  location,
int  format,
int  palCount 
)

Creates a new image and allocates memory in RAM for it

int ulCreateImagePalette ( UL_IMAGE img,
int  location,
int  palCount 
)

Creates a palette for an image. The image must not have a palette already, else this function will fail.

Returns:
1 on success
It is impossible to resize a palette once created, so choose the number of colors carefully.

To allocate the maximum number of colors for each image, use 1 << ul_paletteSizes[imageFormat] as a palette color count.

Important note: the location of the palette MUST be the same as the location of the image texture! If a texture is already loaded, the palette location will be automatically adjusted to match the location of the texture.

Very important: To be used as textures, image dimensions must have a size power of two. The members sysSizeX and sysSizeY indicate the real dimension of data in memory.

UL_IMAGE* ulConvertImageToPaletted ( UL_IMAGE imgOriginal,
int  newLocation,
int  newFormat 
)

Converts a true color image (5550 or 5551) to a paletted format, creating a palette for it. A pointer to the new image is returned and the original image is left untouched.

int ulRealizeImage ( UL_IMAGE img  ) 

Copies an image to Video RAM. It is necessary so that you can draw that image on the screen.

However, the system will realize the image automatically if it's not already done before drawing it.

Please note that when you create or load an image, it will be placed in RAM, and it's accessable by its texture and palette members. Once you've realized it, these pointers will become NULL and image will not be accessable anymore, except if you lock it (search for ulLockImage).

int ulUnrealizeImage ( UL_IMAGE img  ) 

Copies an image back to Main RAM.

This function does the exact opposite of ulRealizeImage, so do it only if it has been realized before. The image and palette will be in RAM back again, so you can modify it. Realize the image again once finished with it, or wait for the system to do it automatically, but remember that it can cause flickering if done during a mid-game frame as discussed in the documentation!

void ulDeleteImage ( UL_IMAGE img  ) 

Deletes an image. The image can be in VRAM (realized) or in main RAM, it doesn't matter.


Generated on Sat Jul 14 23:39:33 2007 by  doxygen 1.5.2