Advanced
[Images]

More advanced routines for manipulating images. More...

Defines

#define ulImageIsPaletted(img)   (img->format >= UL_PF_PAL5_A3 && img->format <= UL_PF_PAL3_A5)
#define ulImageSetRotCenter(img)   ((img)->centerX = ulAbs((img)->offsetX1 - (img)->offsetX0) >> 1, (img)->centerY = ulAbs((img)->offsetY1 - (img)->offsetY0) >> 1)
#define ulGetImageLineAddr(img, y)   ((char*)((img)->texture) + (y)*(((img)->sysSizeX * ul_pixelWidth[(img)->format])>>3))
#define ulGetImagePixelAddr(img, x, y)   ((char*)((img)->texture) + ((((y)*(img)->sysSizeX + (x)) * ul_pixelWidth[(img)->format])>>3))
#define ulGetImageTotalSize(img)   (((img)->sysSizeX * (img)->sysSizeY * ul_pixelWidth[(img)->format]) >> 3)

Functions

void * ulLockImage (UL_IMAGE *img, UL_LOCK_REASON lockReason)
void ulUnlockImage (UL_IMAGE *img, UL_LOCK_REASON lockReason)
void ulSetImagePixel (UL_IMAGE *img, int x, int y, int pixelValue)
int ulGetImagePixel (UL_IMAGE *img, int x, int y)

Variables

u8 ul_firstPaletteColorOpaque

Detailed Description

More advanced routines for manipulating images.


Define Documentation

#define ulImageIsPaletted ( img   )     (img->format >= UL_PF_PAL5_A3 && img->format <= UL_PF_PAL3_A5)

Retrieves wether an image needs a palette or not based on its pixel format

#define ulImageSetRotCenter ( img   )     ((img)->centerX = ulAbs((img)->offsetX1 - (img)->offsetX0) >> 1, (img)->centerY = ulAbs((img)->offsetY1 - (img)->offsetY0) >> 1)

Defines the rotation center of an image to the center of it.

#define ulGetImageLineAddr ( img,
 )     ((char*)((img)->texture) + (y)*(((img)->sysSizeX * ul_pixelWidth[(img)->format])>>3))

Return a pointer to the beginning of an image line pixel data.

#define ulGetImagePixelAddr ( img,
x,
 )     ((char*)((img)->texture) + ((((y)*(img)->sysSizeX + (x)) * ul_pixelWidth[(img)->format])>>3))

Return a pointer to the corresponding pixel of an image.

Please note that some image formats are not byte-boundary, like 2 or 4 bits formats. You'll have to so some more work to set a single pixel on these images.

#define ulGetImageTotalSize ( img   )     (((img)->sysSizeX * (img)->sysSizeY * ul_pixelWidth[(img)->format]) >> 3)

Returns the total size (in bytes) of an image.


Function Documentation

void* ulLockImage ( UL_IMAGE img,
UL_LOCK_REASON  lockReason 
)

Locks an image so that you can access its contents in software. Returns a pointer to the image contents. It's only useful if your image is in VRAM, but you can call this function even if your image is in RAM, it's a safe way to access your image.

You must provide the reason for which you want to lock your image: UL_LOCK_PIXELS (pixel data) or UL_LOCK_PALETTE (palette data). The corresponding pointer will be returned. You can lock both elements with 2 successive calls.

Note: only one image can be locked at a time. Always unlock everything from an image before locking another one.

Note 2: images should be locked for a very small time, especially if they're stored in VRAM, because this will also lock the video memory, making the GPU unable to read from it. If you're doing that during a render, the screen may display transparent bands due to a rendering failure.

void ulUnlockImage ( UL_IMAGE img,
UL_LOCK_REASON  lockReason 
)

Unlocks a locked image. Always unlock the your images shortly after having locked them! You must provide the same reason as the one you used when locking it. If you lock both elements of a single image, you should lock them at the same time, and also unlock them at the same time.

Example:

void *tetxurepointer = ulLockImage(image, UL_LOCK_PIXELS);
void *palettepointer = ulLockImage(image, UL_LOCK_PALETTE);
[use your pointers]
ulUnlockImage(image, UL_LOCK_PALETTE);
ulUnlockImage(image, UL_LOCK_PIXELS);

void ulSetImagePixel ( UL_IMAGE img,
int  x,
int  y,
int  pixelValue 
)

Draws a single pixel on an image.

Parameters:
pixelValue The raw pixel value.
  • A 16-bit color with alpha in 5551
  • A 15-bit color value without alpha in 5550
  • A 8-bit color palette index in PAL8
  • A 5-bit color palette index in PAL5_A3 with the 3 MSB set to the alpha value
  • A 3-bit color palette index in PAL3_A5 with the 5 MSB set to the alpha value
Note that this function is not optimized for speed, but should be okay for most uses. If you need a very fast mean to do it, then you'll have to write your own renderer function, which will be able to draw several pixels at once depending on the image format.

int ulGetImagePixel ( UL_IMAGE img,
int  x,
int  y 
)

Returns the raw value of a pixel on an image. Same considerations as ulSetImagePixel apply.

The return value will be a color if it's a 15 or 16-bit image, it will be a value (palette entry) in other cases.


Variable Documentation

u8 ul_firstPaletteColorOpaque

Treats the first color palette as opaque. When enabled, image loading routines (GIF/PNG/...) will NEVER use the color 0 except if it's transparent (color key and so on). Values:


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