Pixel access
[Images]


Defines
#define	oslGetImageLine(img, y) ((char)((img)->data) + (y)(((img)->realSizeX * osl_pixelWidth[(img)->pixelFormat])>>3))
#define	oslGetImagePixelAddr(img, x, y) ((char)((img)->data) + ((((y)(img)->realSizeX + (x)) * osl_pixelWidth[(img)->pixelFormat])>>3))
Functions
void	oslUncacheImageData (OSL_IMAGE *img)
void	oslUncacheImage (OSL_IMAGE *img)
int	oslGetImagePixel (OSL_IMAGE *img, unsigned int x, unsigned int y)
void	oslSetImagePixel (OSL_IMAGE *img, unsigned int x, unsigned int y, int pixelValue)
void *	oslGetSwizzledPixelAddr (OSL_IMAGE *img, unsigned int x, unsigned int y)
int	oslConvertColor (int pfDst, int pfSrc, int color)
int	oslConvertColorEx (OSL_PALETTE *p, int pfDst, int pfSrc, int color)
void	oslLockImage (OSL_IMAGE *img)
void	oslUnlockImage (OSL_IMAGE *img)
Variables
const int	osl_pixelWidth []
const u8	osl_paletteSizes []

Detailed Description

Low level access to images.

Define Documentation

#define oslGetImageLine	(	img,
		y		)	((char)((img)->data) + (y)(((img)->realSizeX * osl_pixelWidth[(img)->pixelFormat])>>3))

Returns the address of the beginning (left border) of an image line. This address can be used to access image raw data. Please note that when doing this, you'll have to respect the pixelformat of the image! If the image is 16 bits (4444, 5551 or 5650) then use a u16 pointer and appropriate RGBxx macros.

Here is an example which fills one line:

//Create a 15-bit image (16-bit pixel width as 1 alpha bit is added).
OSL_IMAGE *img = oslCreateImage(32, 32, OSL_IN_RAM, OSL_PF_5551);
//Get a pointer to the 4th line (0 is the first, 1 the second, ...)
u16 *data = (u16*)oslGetImageLine(img, 3);
//Loop index variable
int i;
//From the beginning to the end of the line...
for (i=0;i<img->sizeX;i++)              {
        //Set this pixel to bright red
        *data = RGBA15(255, 0, 0, 255);
        //Point to the next pixel
        data++;
}

#define oslGetImagePixelAddr	(	img,
		x,
		y	)	((char)((img)->data) + ((((y)(img)->realSizeX + (x)) * osl_pixelWidth[(img)->pixelFormat])>>3))

Gets the address of a single pixel of an image. Please note that this works only for 8 to 32 bits pixel types, but not for 4 bits, as the byte is the smallest unit you can work with, and in this case a byte contains 2 pixels. In case of 4 bits, a pointer to the corresponding pixel pair (byte) will be returned, and you'll have to use masks to handle this correctly.

Here is an (untested) example:

void setPixel(OSL_IMAGE *img, int x, int y, int value)          {
        u8 *data = oslGetImagePixelAdr(x, y);

        //The pixel value can't be larger than 4 bits, else we would overflow on the next pixel, messing up the display.
        value &= 0xf;

        //First method: is x even?
        if (x & 1)              {
                //Mask out the last 4 bits
                data &= 0x0f;
                //Write to the last 4 bits
                data |= value << 4;
        }
        else    {
                //Mask out the first 4 bits
                data &= 0xf0;
                //Write to the first 4 bits
                data |= value;
        }

        //Second method: directly integrate the parity checking
        data &= ~(15 << ((x & 1) << 2));
        data |= value << ((x & 1) << 2);
}

Function Documentation

void oslUncacheImageData ( OSL_IMAGE * img ) [inline]

Flushes the image data from the cache. Never forget to call this after you've modified an image in a cached way (by default all the following routines do). See oslUncacheData for more information.

Note: this routine does not flush the associated image palette data! Call oslUncacheImage instead if you need it!

void oslUncacheImage ( OSL_IMAGE * img )

Uncache a whole image, including its associated palette (image->palette).

int oslGetImagePixel	(	OSL_IMAGE *	img,
		unsigned int	x,
		unsigned int	y
	)

High-level routine which reads a single pixel on an image. Beware, caching is enabled, so after finished reading and/or writing pixels to an image, please take care to uncache your image! The best and cleaner way to do it is to use oslLockImage and oslUnlockImage. See oslGetImagePixel for an example.

Returns:: The value of the pixel at that position. The value depends on the pixelformat, it can be a palette entry number if the image is paletted, or a color in the format of the image (so you may have to convert it depending on what you'd like).

//Get a 32 bit (OSL_PF_8888) color for the pixel at x, y, whatever its pixelformat is.
pixel = oslConvertColorEx(yourImage->palette, OSL_PF_8888, yourImage->pixelFormat, oslGetImagePixel(yourImage, x, y));

Note: This routine also works for swizzled images!

Note: this routine is rather slow, you should consider raw access if you need good performance.

void oslSetImagePixel	(	OSL_IMAGE *	img,
		unsigned int	x,
		unsigned int	y,
		int	pixelValue
	)

Sets a pixel on the image. Same remarks as for oslGetImagePixel apply. The value is in the destination format of the image (so, either a palette entry or a color in the good format). Use conversions if needed, as shown in the example above. Here is another example that does calculation on every pixel of an image.

//Before doing low level operations on an image, we first need to lock it, it takes care of low level cache operations.
oslLockImage(image);
{
        //The {...} block is just for estethic, not necessary
        for (j=0;j<image->sizeY;j++)            {
                for (i=0;i<image->sizeX;i++)            {
                        //Get a pixel of the image (depends on its pixelformat, here we assume it's 8888)
                        u32 pixel = oslGetImagePixel(image, i, j);
                        //Mask out the green and blue components
                        oslSetImagePixel(image, i, j, pixel & 0xff0000ff);
                }
        }
}
oslUnlockImage(image);

void* oslGetSwizzledPixelAddr	(	OSL_IMAGE *	img,
		unsigned int	x,
		unsigned int	y
	)

Returns the address of a pixel, working even if the image is swizzled. This implementation is slower but works in every case.

int oslConvertColor	(	int	pfDst,
		int	pfSrc,
		int	color
	)

Converts a color.

Parameters:

	pfDst	Destination pixel format.
	pfSrc	Source pixel format.
	color	Color (in the source pixel format).

int oslConvertColorEx	(	OSL_PALETTE *	p,
		int	pfDst,
		int	pfSrc,
		int	color
	)

Converts a color but using a palette if either the source or destination pixel format are paletted. See oslGetImagePixel for an example of use.

void oslLockImage ( OSL_IMAGE * img )

Locks an image, so that you can access it. Althrough not necessary, this is a good thing to do because it will automatically handle drawing to the drawbuffer, uncaching the image when finished and flushing the texture cache to avoid render errors when an image is modified while it's being drawn.

//Lock the image
oslLockImage(myImage);
{
        //Do some software access to the image
        u16 *ptr = (u16*)myImage->data;
        *ptr = 0;
}
//Unlock it after having finished
oslUnlockImage(myImage);

//We can now draw it!
oslDrawImage(myImage);

void oslUnlockImage ( OSL_IMAGE * img )

Unlock the image after you've finished with it.

Variable Documentation

const int osl_pixelWidth[]

List of pixel widths (in bits) for each pixel format.

const u8 osl_paletteSizes[]

List of palette sizes (in powers of two). For non-paletted formats, it is zero. Else you can get the palette size by doing 1 << osl_paletteSizes[pixelFormat].

Pixel access [Images]

Defines

Functions

Variables

Detailed Description

Define Documentation

Function Documentation

Variable Documentation

Pixel access
[Images]