Pixel access

Macros
#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))
#define	oslGetImagePixelAdr   oslGetImagePixelAddr

Functions
static 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)
	Converts a color from one pixel format to another.
int	oslConvertColorEx (OSL_PALETTE *p, int pfDst, int pfSrc, int color)
	Converts a color between different pixel formats, optionally using a palette for indexed formats.
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.

Macro Definition Documentation

oslGetImageLine

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

Returns the address of the beginning (left border) of a specific line in an image.

This macro provides access to the raw data of a specific line in the image. When using this macro, make sure to respect the pixel format of the image. For images with 16-bit pixel formats (e.g., 4444, 5551, or 5650), use a u16 pointer and the appropriate RGBxx macros for accessing pixel values.

Parameters

img	Pointer to the image from which the line address is obtained.
y	The line number (0 is the first line, 1 is the second, and so on).

Returns

A pointer to the beginning of the specified line in the image's raw data.

Example:

// Create a 15-bit image (16-bit pixel width, with 1 alpha bit included)
OSL_IMAGE *img = oslCreateImage(32, 32, OSL_IN_RAM, OSL_PF_5551);
 
// Get a pointer to the 4th line (0-based index)
u16 *data = (u16*)oslGetImageLine(img, 3);
 
        // Loop through each pixel in the line
for (int i = 0; i < img->sizeX; i++) {
        // Set this pixel to bright red
        (*data) = RGBA15(255, 0, 0, 255);
        // Move to the next pixel
        data++;
}

Note:

• Ensure you use the correct pixel format and data type when accessing raw image data.

oslGetImagePixelAddr

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

Gets the address of a single pixel in an image.

This macro provides a pointer to the address of a specific pixel in the image. It is designed to work with pixel formats ranging from 8 to 32 bits per pixel. Note that this macro does not handle 4-bit images correctly, as a byte in 4-bit images represents two pixels. For 4-bit images, this macro returns a pointer to the corresponding byte, and additional bit manipulation is required to access individual pixels.

Parameters

img	Pointer to the image from which to retrieve the pixel address.
x	The x-coordinate of the pixel.
y	The y-coordinate of the pixel.

Returns

A pointer to the address of the specified pixel in the image's raw data.

Example:

void setPixel(OSL_IMAGE *img, int x, int y, int value) {
        u8 *data = (u8 *)oslGetImagePixelAddr(img, x, y);
 
        // Ensure the pixel value does not exceed the bit depth
        value &= 0xf;
 
        // Handle 4-bit images by checking if x is even or odd
        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;
        }
 
         // Alternative method with parity checking
        (*data) &= ~(15 << ((x & 1) << 2));
        (*data) |= value << ((x & 1) << 2);
}

Note:

• Ensure that you handle the pixel data according to its format and bit depth. For 4-bit images, additional bit manipulation is required.

oslGetImagePixelAdr

#define oslGetImagePixelAdr   oslGetImagePixelAddr

For backward compatibility.

Function Documentation

oslUncacheImageData()

static void oslUncacheImageData ( OSL_IMAGE *  img )

inlinestatic

Flushes the image data from the cache.

This function is necessary to call after modifying an image's data directly (e.g., manipulating img->data manually). It ensures that the image data is properly written back and invalidated in the cache.

Parameters

img	Pointer to the image whose data needs to be flushed from the cache.

Note:

• This routine only flushes the image data and does not affect the associated palette data. To flush the palette data as well, use oslUncacheImage.

OSL_IMAGE *img = your image;
// Modify the image data manually
oslUncacheImageData(img); // Ensure changes are flushed

oslUncacheImage()

void oslUncacheImage ( OSL_IMAGE *  img )

extern

Uncaches an entire image, including its associated palette.

This function not only flushes the image data from the cache but also handles the associated palette data, ensuring that both are properly uncached.

Parameters

img	Pointer to the image to be uncached.

Note:

• This routine is a comprehensive solution for ensuring that all parts of the image (data and palette) are properly managed in memory.

OSL_IMAGE *img = your image;
oslUncacheImage(img); // Flushes image data and associated palette

oslGetImagePixel()

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

extern

High-level routine to read a single pixel from an image.

This function retrieves the value of a pixel at a specified position from an image. It reads through the uncached address, so it sees what is in memory: if you wrote the image through img->data (cached), call oslUncacheImage first.

Parameters

img	Pointer to the image from which the pixel is read.
x	The x-coordinate of the pixel to be read.
y	The y-coordinate of the pixel to be read.

Returns

The value of the pixel at the specified position. The returned value depends on the pixel format of the image. It could be a palette entry number for paletted images or a color value in the image's format. You might need to convert this value depending on your needs.

Example:

// Get a 32-bit (OSL_PF_8888) color for the pixel at x, y, regardless of the image's pixel format.
int pixel = oslConvertColorEx(yourImage->palette, OSL_PF_8888, yourImage->pixelFormat, oslGetImagePixel(yourImage, x, y));

Note:

• This function works for both regular and swizzled images.
• It may be slower compared to raw access methods; consider using raw access if performance is critical.

oslSetImagePixel()

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

extern

Sets a pixel value on the image.

This function sets the value of a pixel at a specified position in the image. The value should be in the image's destination format, which could be a palette entry or a color value. If needed, perform conversions to match the image's format.

Parameters

img	Pointer to the image where the pixel will be set.
x	The x-coordinate of the pixel to be set.
y	The y-coordinate of the pixel to be set.
pixelValue	The value to set at the specified pixel position. This value should be in the format used by the image (e.g., a color value or a palette entry).

Example:

// Before performing low-level operations on an image, lock it to handle cache operations.
oslLockImage(image);
{
        // Iterate over all pixels in the image
        for (j = 0; j < image->sizeY; j++) {
                for (i = 0; i < image->sizeX; i++) {
                        // Get the current pixel value (assuming a 8888 format here)
                        u32 pixel = oslGetImagePixel(image, i, j);
                        // Mask out the green and blue components
                        oslSetImagePixel(image, i, j, pixel & 0xff0000ff);
                }
        }
}
oslUnlockImage(image);

Note:

• The pixel is written through the uncached address, so it reaches memory without a CPU cache writeback. The GE may still hold the old texels if the image was already drawn: call oslUncacheImage (or wrap the writes in oslLockImage / oslUnlockImage) before drawing it again.

oslGetSwizzledPixelAddr()

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

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

Parameters

img	Pointer to the OSL_IMAGE structure representing the image.
x	The x-coordinate of the pixel.
y	The y-coordinate of the pixel.

Returns

A pointer to the address of the pixel in the image's raw data. The exact type of this pointer depends on the image's pixel format and needs to be cast appropriately.

Note

This function is designed to handle swizzled images. It might be slower than direct access methods, but it ensures correct behavior for swizzled images by accounting for the swizzling pattern.

// Example usage:
OSL_IMAGE *img = Load or create your image;
void *pixelAddr = oslGetSwizzledPixelAddr(img, x, y);
 
// Depending on the pixel format, cast the pointer to the appropriate type
u32 *pixelData = (u32*)pixelAddr;
 
// Now you can read or modify the pixel data
*pixelData = New pixel value;

oslConvertColor()

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

extern

Converts a color from one pixel format to another.

This function converts a color value from the source pixel format (pfSrc) to the destination pixel format (pfDst). It supports various pixel formats, including OSL_PF_8888, OSL_PF_5650, OSL_PF_5551, and OSL_PF_4444.

Parameters

pfDst	The destination pixel format. This can be one of the OSL_PF_* values (e.g., OSL_PF_8888, OSL_PF_5650).
pfSrc	The source pixel format. This can be one of the OSL_PF_* values (e.g., OSL_PF_8888, OSL_PF_5650).
color	The color value to be converted, expressed in the source pixel format.

Returns

The color converted to the destination pixel format.

oslConvertColorEx()

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

extern

Converts a color between different pixel formats, optionally using a palette for indexed formats.

This function converts a color from one pixel format (pfSrc) to another (pfDst). If either the source or destination format is a paletted format (OSL_PF_8BIT or OSL_PF_4BIT), the provided palette (p) will be used for the conversion.

Note

If the source and destination formats are the same, the original color is returned without modification.

Parameters

p	Pointer to an OSL_PALETTE structure. This is used when the source or destination format is paletted. If p is NULL, the conversion will be done without using a palette.
pfDst	The destination pixel format. This can be any of the OSL_PF_* values (e.g., OSL_PF_8888, OSL_PF_5650).
pfSrc	The source pixel format. This can be any of the OSL_PF_* values (e.g., OSL_PF_8888, OSL_PF_5650).
color	The color value to be converted.

Returns

The color converted to the destination pixel format.

oslLockImage()

void oslLockImage ( OSL_IMAGE *  img )

extern

Locks an image to ensure safe access and modifications. This function automatically handles drawing to the drawbuffer, uncaching the image when finished, and flushing the texture cache to avoid rendering issues when the image is modified during drawing.

Parameters

img	Pointer to the OSL_IMAGE structure representing the image to lock.

Note

While locking an image is not strictly necessary, it is highly recommended as it ensures proper management of image access and rendering, preventing potential errors caused by concurrent modifications and drawing operations.

// Lock the image to safely modify it
oslLockImage(myImage);
{
    // Perform software access and modification to the image
    u16 *ptr = (u16*)myImage->data;
    *ptr = 0; // Example modification
}
// Unlock the image after modifications are complete
oslUnlockImage(myImage);
 
// Now you can safely draw the modified image
oslDrawImage(myImage);

oslUnlockImage()

void oslUnlockImage ( OSL_IMAGE *  img )

extern

Unlocks an image after modifications have been completed. This function should be called after using oslLockImage to release the lock and finalize any pending operations.

Parameters

img	Pointer to the OSL_IMAGE structure representing the image to unlock.

Note

Always ensure that oslUnlockImage is called after oslLockImage to properly finalize modifications and ensure the image is ready for rendering or further operations.

Variable Documentation

osl_pixelWidth

const int osl_pixelWidth[]

extern

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

This array provides the number of bits used for each pixel in various pixel formats. The index of the array corresponds to the pixel format identifier.

Note

For example, if osl_pixelWidth[OSL_PF_8888] is 32, it indicates that the OSL_PF_8888 pixel format uses 32 bits per pixel.

osl_paletteSizes

const u8 osl_paletteSizes[]

extern

List of palette sizes (in powers of two) for each pixel format.

This array provides the size of the palette for each pixel format that uses palette-based color representation. For non-paletted formats, the value is zero. For paletted formats, the size of the palette can be calculated as 1 << osl_paletteSizes[pixelFormat], where pixelFormat is the index into the array.

Note

For example, if osl_paletteSizes[OSL_PF_4BIT] is 4, it indicates that the OSL_PF_4BIT pixel format uses a palette size of 1 << 4, or 16 colors.