Pixel access

Macros
#define	oslGetImageLine(img, y)
#define	oslGetImagePixelAddr(img, x, y)
#define	oslGetImagePixelAdr   oslGetImagePixelAddr

Functions
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 )

Value:

((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.

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

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

\b Example:
\code
// 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++;
}
\endcode

\b Note:
- Ensure you use the correct pixel format and data type when accessing raw image data.

oslGetImagePixelAddr

#define oslGetImagePixelAddr	(		img,
			x,
			y )

Value:

((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.

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

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

\b Example:
\code
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);
}
\endcode

\b 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

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.

@param img
    Pointer to the image to be uncached.

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

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

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. Note that caching is enabled, so after reading and/or writing pixels, you should uncache the image. The recommended approach is to use #oslLockImage and #oslUnlockImage for proper management. For an example of usage, see #oslGetImagePixel.

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

@return
    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.

\b Example:
\code
// 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));
\endcode

\b 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.

@param img
    Pointer to the image where the pixel will be set.
@param x
    The x-coordinate of the pixel to be set.
@param y
    The y-coordinate of the pixel to be set.
@param 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).

\b Example:
\code
// 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);
\endcode

\b Note:
- Similar caching considerations apply as with #oslGetImagePixel. Make sure to manage the image cache properly by locking and unlocking the image.

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.