Image manipulation

Enumerations
enum	OSL_WRITE_FLAGS { OSL_WRI_ALPHA = 1 }

Functions
OSL_IMAGE *	oslCreateImageTile (OSL_IMAGE *img, int offsetX0, int offsetY0, int offsetX1, int offsetY1)
OSL_IMAGE *	oslCreateImageTileSize (OSL_IMAGE *img, int offsetX0, int offsetY0, int width, int height)
OSL_IMAGE *	oslConvertImageTo (OSL_IMAGE *imgOriginal, int newLocation, int newFormat)
OSL_IMAGE *	oslCreateImageCopy (OSL_IMAGE *src, int newLocation)
OSL_IMAGE *	oslCreateSwizzledImage (OSL_IMAGE *src, int newLocation)
void	oslCopyImageTo (OSL_IMAGE *imgDst, OSL_IMAGE *imgSrc)
void	oslSwizzleImage (OSL_IMAGE *img)
void	oslUnswizzleImage (OSL_IMAGE *img)
void	oslSwizzleImageTo (OSL_IMAGE *imgDst, OSL_IMAGE *imgSrc)
bool	oslMoveImageTo (OSL_IMAGE *img, int newLocation)
void	oslClearImage (OSL_IMAGE *img, int color)
int	oslWriteImageFile (OSL_IMAGE *img, const char *filename, int flags)
int	oslWriteImageFilePNG (OSL_IMAGE *img, const char *filename, int flags)
void	oslResetImageProperties (OSL_IMAGE *img)
void	oslScaleImage (OSL_IMAGE *dstImg, OSL_IMAGE *srcImg, int newX, int newY, int newWidth, int newHeight)
OSL_IMAGE *	oslScaleImageCreate (OSL_IMAGE *img, short newLocation, int newWidth, int newHeight, short newPixelFormat)

Detailed Description

Image manipulation in OSLib.

Enumeration Type Documentation

OSL_WRITE_FLAGS

enum OSL_WRITE_FLAGS

Enum for specifying write flags when saving an image to a file.

The flags determine how the image data is processed when written to a file. For example, flags can control whether the alpha channel is included in the output file.

See also

oslWriteImageFilePNG for details on specific write flags.

Note

Use these flags to customize the behavior of image writing functions.

int flags = OSL_WRI_ALPHA; // Include alpha channel when writing the image
oslWriteImageFile(myImage, "output.png", flags);

Enumerator
OSL_WRI_ALPHA	Writes the alpha channel of the image. If set, the alpha channel data will be included in the output file.

Function Documentation

oslCreateImageTile()

OSL_IMAGE * oslCreateImageTile ( OSL_IMAGE *  img, int  offsetX0, int  offsetY0, int  offsetX1, int  offsetY1  )

extern

Creates an alternate image referencing a part (tile) of another one.

Parameters

img	The original image from which a tile will be created.
offsetX0	The starting x position of the image part to reference.
offsetY0	The starting y position of the image part to reference.
offsetX1	The ending x position of the image part to reference.
offsetY1	The ending y position of the image part to reference.

This will return a pointer to a new image, but the data will not be copied to the new image. Instead, it will reference the original image data. When you delete the new image, the original image will be left unchanged; only the size of an OSL_IMAGE will be freed from memory (about 80 bytes). However, if you delete the original image, the new one will be unusable. Attempting to draw it may result in corrupt data, and writing to it may cause a crash.

Example usage:

OSL_IMAGE *imageTile = oslCreateImageTile(originalImage, 0, 0, 32, 32);
oslDrawImage(imageTile);                                  // Will draw a 32x32 image inside of originalImage
oslDeleteImage(imageTile);                                // Only frees the copy, the original remains untouched!

This routine was meant to create individual "sprite" images from a big one and manipulate them easily. However, as it's not very clear, it's advised to avoid using it. An alternative approach would be:

oslSetImageTile(originalImage, 0, 0, 32, 32);
oslDrawImage(originalImage);                              // Will draw a 32x32 image inside of originalImage

oslCreateImageTileSize()

OSL_IMAGE * oslCreateImageTileSize ( OSL_IMAGE *  img, int  offsetX0, int  offsetY0, int  width, int  height  )

extern

Creates an alternate image referencing a part (tile) of another one using width and height.

Parameters

img	The original image from which a tile will be created.
offsetX0	The starting x position of the image part to reference.
offsetY0	The starting y position of the image part to reference.
width	The width of the image part to reference.
height	The height of the image part to reference.

This function returns a pointer to a new image, but the data will not be copied to the new image. Instead, it will reference the original image data. When you delete the new image, the original image will be left unchanged; only the size of an OSL_IMAGE will be freed from memory (about 80 bytes). However, if you delete the original image, the new one will be unusable. Attempting to draw it may result in corrupt data, and writing to it may cause a crash.

Example usage:

OSL_IMAGE *imageTile = oslCreateImageTileSize(originalImage, 0, 0, 32, 32);
oslDrawImage(imageTile);                                  // Will draw a 32x32 image inside of originalImage
oslDeleteImage(imageTile);                                // Only frees the copy, the original remains untouched!

This routine was designed to create individual "sprite" images from a large image using width and height specifications. An alternative approach for creating image tiles is using coordinates with the oslSetImageTile function.

oslConvertImageTo()

OSL_IMAGE * oslConvertImageTo ( OSL_IMAGE *  imgOriginal, int  newLocation, int  newFormat  )

extern

Converts an image to another pixel format and places it in another location.

Parameters

imgOriginal	The original image to be converted.
newLocation	The location where the converted image should be placed. Common locations include OSL_IN_RAM and OSL_IN_VRAM.
newFormat	The pixel format to convert the image to, such as OSL_PF_5551, OSL_PF_8888, etc.

On success, this function deletes the original image and returns the converted image. On allocation failure, it returns NULL and leaves the original image unchanged and owned by the caller.

Example usage:

OSL_IMAGE *converted = oslConvertImageTo(image, OSL_IN_RAM, OSL_PF_5551);
if (converted) image = converted;

After a successful conversion, imgOriginal must no longer be used. Delete the returned image when it is no longer needed.

oslCreateImageCopy()

OSL_IMAGE * oslCreateImageCopy ( OSL_IMAGE *  src, int  newLocation  )

extern

Creates a copy of an image.

Parameters

src	The source image to be copied.
newLocation	The location where the copied image should be placed. Common locations include OSL_IN_RAM and OSL_IN_VRAM.

This function creates a complete copy of the source image, including its image data. The returned image is a new instance, independent of the original. Changes to the copied image will not affect the source image and vice versa.

Example usage:

OSL_IMAGE *originalImage = oslLoadImageFile("example.png", OSL_IN_RAM, OSL_PF_8888);
OSL_IMAGE *copiedImage = oslCreateImageCopy(originalImage, OSL_IN_VRAM);
// Now you can use copiedImage independently of originalImage

Both the original and copied images are not linked together. Ensure to manage and free the memory for both images as needed.

oslCreateSwizzledImage()

OSL_IMAGE * oslCreateSwizzledImage ( OSL_IMAGE *  src, int  newLocation  )

extern

Creates a copy of an image and swizzles the new one.

Parameters

src	The source image to be copied.
newLocation	The location where the swizzled image should be placed. Common locations include OSL_IN_RAM and OSL_IN_VRAM.

This function creates a complete copy of the source image and applies swizzling to the new image. Swizzling is a technique used to improve texture performance by rearranging the image data. The returned image is a new instance, independent of the original.

Example usage:

OSL_IMAGE *originalImage = oslLoadImageFile("example.png", OSL_IN_RAM, OSL_PF_8888);
OSL_IMAGE *swizzledImage = oslCreateSwizzledImage(originalImage, OSL_IN_VRAM);
// Now you can use swizzledImage independently of originalImage

Both the original and swizzled images are not linked together. Ensure to manage and free the memory for both images as needed.

oslCopyImageTo()

void oslCopyImageTo ( OSL_IMAGE *  imgDst, OSL_IMAGE *  imgSrc  )

extern

Copies the content of one image to another.

Parameters

imgDst	The destination image where the content will be copied to.
imgSrc	The source image from which the content will be copied.

This function copies the image data from imgSrc to imgDst. Both images must have the same dimensions (width and height) and pixel format. If the formats do not match, the copy operation will fail, and the destination image may not be updated correctly.

Note: This function only copies the image data and does not change the properties of imgDst. Ensure that imgDst has been properly initialized and allocated with the same format and size as imgSrc.

Example usage:

OSL_IMAGE *sourceImage = oslLoadImageFile("source.png", OSL_IN_RAM, OSL_PF_8888);
OSL_IMAGE *destinationImage = oslCreateImage(sourceImage->sizeX, sourceImage->sizeY, OSL_IN_RAM, OSL_PF_8888);
oslCopyImageTo(destinationImage, sourceImage);
// Now destinationImage contains a copy of the sourceImage data

Ensure both images have the same properties before calling this function to avoid unexpected behavior.

oslSwizzleImage()

void oslSwizzleImage ( OSL_IMAGE *  img )

extern

Swizzles an image to improve drawing performance.

Parameters

img	The image to be swizzled.

Swizzling is a process that optimizes image drawing performance by reorganizing the image data into a format that is more efficient for the GPU to handle. After swizzling, the image can be drawn much faster. However, swizzled images cannot be modified directly due to their special format.

If you need to modify the image after swizzling, you will need to unswizzle it, which can be slow. Therefore, it is recommended to swizzle images that are stored in RAM and are not intended to be modified frequently.

Hint: When loading images, use the OSL_SWIZZLED bit to automatically swizzle images for convenience.

Example usage:

OSL_IMAGE *image = oslLoadImageFile("example.png", OSL_IN_RAM, OSL_PF_8888);
oslSwizzleImage(image);
// The image is now swizzled and can be drawn faster

Be cautious with unswizzling images frequently, as it can impact performance. Use swizzling for images that are primarily used for rendering and do not require modifications.

oslUnswizzleImage()

void oslUnswizzleImage ( OSL_IMAGE *  img )

extern

Restores an image from its swizzled format to its original format.

Parameters

img	The swizzled image to be unswizzled.

This function performs the opposite operation of oslSwizzleImage, converting the swizzled image back to its original format. After unswizzling, the image will be accessible for raw reading and writing.

Note that unswizzling an image can be a slow process, so it should be used judiciously. It's generally best to swizzle images for performance improvements and avoid frequent unswizzling unless necessary.

Example usage:

OSL_IMAGE *swizzledImage = oslLoadImageFile("example.png", OSL_IN_RAM, OSL_PF_8888);
oslSwizzleImage(swizzledImage);
// Use the image for fast drawing
oslUnswizzleImage(swizzledImage);
// Now you can read or write to the image directly

Make sure to only unswizzle images that were previously swizzled to avoid potential issues with image data integrity.

oslSwizzleImageTo()

void oslSwizzleImageTo ( OSL_IMAGE *  imgDst, OSL_IMAGE *  imgSrc  )

extern

Swizzles an image and writes the result to another image.

Parameters

imgDst	The destination image where the swizzled data will be written. This image must have enough memory allocated to hold the swizzled data.
imgSrc	The source image that will be swizzled.

This function swizzles the imgSrc image and writes the swizzled result to imgDst. This routine is considered outdated. For modern usage, it is recommended to use oslSwizzleImage which operates directly on a single image.

Example usage:

OSL_IMAGE *sourceImage = oslLoadImageFile("example.png", OSL_IN_RAM, OSL_PF_8888);
OSL_IMAGE *destinationImage = oslCreateImage(sourceImage->sizeX, sourceImage->sizeY, OSL_IN_RAM, OSL_PF_8888);
oslSwizzleImageTo(destinationImage, sourceImage);
// Use destinationImage for fast drawing

Note: Ensure that imgDst has been properly allocated and has sufficient size to accommodate the swizzled image data from imgSrc.

oslMoveImageTo()

bool oslMoveImageTo ( OSL_IMAGE *  img, int  newLocation  )

extern

Moves an image to a new location in memory.

Parameters

img	The image to be moved.
newLocation	The new location where the image should be moved. This can be either OSL_IN_RAM or OSL_IN_VRAM.

This function relocates an image to a new memory location. The new location can be either RAM or VRAM. After moving, the image can be used in its new location, but note that moving images between different memory types might have implications for performance and accessibility.

Example usage:

OSL_IMAGE *image = oslLoadImageFile("example.png", OSL_IN_RAM, OSL_PF_8888);
oslMoveImageTo(image, OSL_IN_VRAM);
// Now the image is in VRAM and can be used for rendering

Returns true if the move was successful, and false otherwise.

oslClearImage()

void oslClearImage ( OSL_IMAGE *  img, int  color  )

extern

Clears an image with a specific value.

Parameters

img	The image to be cleared. This image must be properly allocated and must have a format compatible with the provided color value.
color	The color value used to clear the image. The format of this color value depends on the pixel format of the image. For example: If the image format is OSL_PF_4BIT, the color value is a palette entry number. If the image format is OSL_PF_5551, the color value is a 15-bit color with alpha.

This function fills the entire image with the specified color value. The color is applied according to the image's pixel format. For instance, in a OSL_PF_4444 format, you might use a 16-bit color value where each channel has 4 bits.

Example usage:

OSL_IMAGE *img = oslCreateImage(32, 32, OSL_IN_RAM, OSL_PF_4444);
// Clear the image to black with full opacity (alpha=255)
oslClearImage(img, RGBA12(0, 0, 0, 255));

Note: The color parameter must be appropriate for the image's pixel format. The provided value should match the format's bit depth and channel order.

oslWriteImageFile()

int oslWriteImageFile ( OSL_IMAGE *  img, const char *  filename, int  flags  )

extern

Writes an image to a file.

Parameters

img	The image to be written to the file. This image must not be swizzled; if it is, the function will not perform any operation.
filename	The path to the file where the image will be saved. The file type is determined based on the file extension.
flags	Either 0 or OSL_WRI_ALPHA, see oslWriteImageFilePNG.

Returns

1 if the image was written, 0 otherwise (swizzled image, unsupported extension or write error).

This function saves the provided image to the specified file. The file type is picked from the extension, in any case; PNG (.png) is the only format OSLib writes.

Note: If the image is swizzled, the function will not perform any action. To write a swizzled image, you must first unswizzle it using the oslUnswizzleImage function.

Example usage:

OSL_IMAGE *img = oslCreateImage(64, 64, OSL_IN_RAM, OSL_PF_5551);
// Assuming img is properly initialized and contains image data
int result = oslWriteImageFile(img, "output_image.png", 0);
if (result) {
        // Image was written successfully
} else {
        // Error occurred
}

oslWriteImageFilePNG()

int oslWriteImageFilePNG ( OSL_IMAGE *  img, const char *  filename, int  flags  )

extern

Writes an image to a PNG file. Same remarks as oslWriteImageFile apply.

Parameters

img	The image you want to write.
filename	The name of the file that you want to write to.
flags	Either 0 or OSL_WRI_ALPHA. If OSL_WRI_ALPHA is specified, the alpha will be written to the PNG image file, making it semi-transparent. Else, alpha is ignored and always set to opaque.

You can pass for example OSL_SECONDARY_BUFFER (the buffer which is currently displayed on the screen) to take a screenshot.

oslWriteImageFilePNG(OSL_SECONDARY_BUFFER, "screenshot.png", 0);

Note: The same considerations as oslWriteImageFile apply.

oslResetImageProperties()

void oslResetImageProperties ( OSL_IMAGE *  img )

extern

Resets the properties of an image, including its position, tile settings, angle, rotation center, and stretching.

Parameters

img	The image whose properties will be reset.

This function resets the following properties of the image:

• Position: The image's current position will be reset to its default.
• Image Tile: Any modifications to the image tile (e.g., using oslSetImageTile) will be cleared.
• Angle: Any rotation applied to the image will be reset.
• Rotation Center: The center used for rotation will be reset.
• Stretching: Any stretching applied to the image will be reset.

Example usage:

OSL_IMAGE *img = oslCreateImage(64, 64, OSL_IN_RAM, OSL_PF_5551);
// Modify image properties
oslResetImageProperties(img);

oslScaleImage()

void oslScaleImage ( OSL_IMAGE *  dstImg, OSL_IMAGE *  srcImg, int  newX, int  newY, int  newWidth, int  newHeight  )

extern

Draws srcImg to dstImg with scaling applied.

Parameters

dstImg	The destination image where the scaled source image will be drawn.
srcImg	The source image to be scaled and drawn.
newX	The x-coordinate for the position of the scaled source image in the destination image.
newY	The y-coordinate for the position of the scaled source image in the destination image.
newWidth	The width of the scaled source image.
newHeight	The height of the scaled source image.

This function scales the source image (srcImg) and draws it onto the destination image (dstImg) at the specified position and with the specified dimensions.

Note

An indexed (4 or 8-bit) source is read through its palette. An indexed destination needs a source in its own format: each pixel then takes the index under it (no blending), so dstImg should use srcImg's palette. Otherwise dstImg is left untouched.

Example usage:

OSL_IMAGE *srcImg = oslCreateImage(64, 64, OSL_IN_RAM, OSL_PF_5551);
OSL_IMAGE *dstImg = oslCreateImage(128, 128, OSL_IN_RAM, OSL_PF_5551);
// Scale and draw srcImg onto dstImg
oslScaleImage(dstImg, srcImg, 10, 10, 100, 100);

oslScaleImageCreate()

OSL_IMAGE * oslScaleImageCreate ( OSL_IMAGE *  img, short  newLocation, int  newWidth, int  newHeight, short  newPixelFormat  )

extern

Creates a scaled copy of an image.

Parameters

img	The image to be scaled and copied.
newLocation	The location where the new scaled image will be stored (e.g., in RAM or VRAM).
newWidth	The width of the scaled image.
newHeight	The height of the scaled image.
newPixelFormat	The pixel format of the new scaled image.

Returns

A pointer to the new scaled image. If the scaling operation fails, the function may return NULL.

This function creates a new image that is a scaled version of the original image (img). The new image will have the specified dimensions and pixel format.

Note

An indexed (4 or 8-bit) image is read through its palette. Scaled to its own indexed format, it keeps its indices (the one under each pixel, no blending) and gets a copy of its palette; to another indexed format, NULL is returned.

Example usage:

OSL_IMAGE *originalImg = oslCreateImage(64, 64, OSL_IN_RAM, OSL_PF_5551);
OSL_IMAGE *scaledImg = oslScaleImageCreate(originalImg, OSL_IN_RAM, 128, 128, OSL_PF_5551);