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 oslWriteImageFilePNG for details on specific write flags.

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

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

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.

@param img
The original image from which a tile will be created.
@param offsetX0
The starting x position of the image part to reference.
@param offsetY0
The starting y position of the image part to reference.
@param offsetX1
The ending x position of the image part to reference.
@param 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:
\code
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!
\endcode

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:
\code
oslSetImageTile(originalImage, 0, 0, 32, 32);
oslDrawImage(originalImage); // Will draw a 32x32 image inside of originalImage
\endcode

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

@param img
    The original image from which a tile will be created.
@param offsetX0
    The starting x position of the image part to reference.
@param offsetY0
    The starting y position of the image part to reference.
@param width
    The width of the image part to reference.
@param 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:
\code
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!
\endcode

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.

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

This function converts an image to a different pixel format and places it in a specified location. The original image may have been moved or modified
during the conversion process, so you should use the returned image instead of the original one.

Example usage:
\code
image = oslConvertImageTo(image, OSL_IN_RAM, OSL_PF_5551);
\endcode

After calling this function, the `imgOriginal` image should no longer be used directly. Instead, the function returns a new image with the specified
pixel format and location. Ensure to properly manage and delete the converted image as needed.

◆ oslCreateImageCopy()

OSL_IMAGE * oslCreateImageCopy	(	OSL_IMAGE *	src,
		int	newLocation )

extern

Creates a copy of an image.

@param src
    The source image to be copied.
@param 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:
\code
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
\endcode

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.

@param src
    The source image to be copied.
@param 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:
\code
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
\endcode

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.

@param imgDst
    The destination image where the content will be copied to.
@param 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:
\code
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
\endcode

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.

@param 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:
\code
OSL_IMAGE *image = oslLoadImageFile("example.png", OSL_IN_RAM, OSL_PF_8888);
oslSwizzleImage(image);
// The image is now swizzled and can be drawn faster
\endcode

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.

@param 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:
\code
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
\endcode

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.

@param imgDst
    The destination image where the swizzled data will be written. This image must have enough memory allocated to hold the swizzled data.
@param 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:
\code
OSL_IMAGE *sourceImage = oslLoadImageFile("example.png", OSL_IN_RAM, OSL_PF_8888);
OSL_IMAGE *destinationImage = oslCreateImage(sourceImage->sizeX, sourceImage->sizeY, OSL_PF_8888);
oslSwizzleImageTo(destinationImage, sourceImage);
// Use destinationImage for fast drawing
\endcode

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.

@param img
    The image to be moved.
@param 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:
\code
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
\endcode

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.

@param img
    The image to be cleared. This image must be properly allocated and must have a format compatible with the provided color value.
@param 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:
\code
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));
\endcode

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.

@param 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.
@param filename
    The path to the file where the image will be saved. The file type is determined based on the file extension.
@param flags
    Options for the image writing operation. These flags control how the image is processed during writing. The specific flags available depend on the implementation and version of OSLib.

@return
    Returns a status code indicating the success or failure of the operation. The exact values and meaning of the return codes depend on the implementation.

This function saves the provided image to the specified file. The file type is automatically detected based on the file extension, which includes support for various formats. However, using this function can increase the size of your project and use unnecessary RAM because it supports every possible format.

\b 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:
\code
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 == 0) {
    // Image was written successfully
} else {
    // Error occurred
}
\endcode

◆ 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);

OSL_SECONDARY_BUFFER

#define OSL_SECONDARY_BUFFER

Definition drawing.h:2946

oslWriteImageFilePNG

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

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.

@param 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:
\code
OSL_IMAGE *img = oslCreateImage(64, 64, OSL_IN_RAM, OSL_PF_5551);
// Modify image properties
oslResetImageProperties(img);
\endcode

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

@param dstImg
    The destination image where the scaled source image will be drawn.
@param srcImg
    The source image to be scaled and drawn.
@param newX
    The x-coordinate for the position of the scaled source image in the destination image.
@param newY
    The y-coordinate for the position of the scaled source image in the destination image.
@param newWidth
    The width of the scaled source image.
@param 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.

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

◆ oslScaleImageCreate()

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

extern

Creates a scaled copy of an image.

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

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

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

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ OSL_WRITE_FLAGS

Function Documentation

◆ oslCreateImageTile()

◆ oslCreateImageTileSize()

◆ oslConvertImageTo()

◆ oslCreateImageCopy()

◆ oslCreateSwizzledImage()

◆ oslCopyImageTo()

◆ oslSwizzleImage()

◆ oslUnswizzleImage()

◆ oslSwizzleImageTo()

◆ oslMoveImageTo()

◆ oslClearImage()

◆ oslWriteImageFile()

◆ oslWriteImageFilePNG()

◆ oslResetImageProperties()

◆ oslScaleImage()

◆ oslScaleImageCreate()