Topics
	Drawing images

	Image placement

	Image manipulation

	Simili sprite system

	Image palettes

	Pixel access

	Drawbuffers

	Advanced

Data Structures
struct	OSL_PALETTE
	Structure representing a palette. More...

struct	OSL_IMAGE
	Structure representing an image loaded in memory. More...

Macros
#define	OSL_PALETTEDATA16 unsigned short __attribute__((aligned(16)))
	Type definition for 16-bit palette data.

#define	OSL_PALETTEDATA32 unsigned long __attribute__((aligned(16)))
	Type definition for 32-bit palette data.

#define	oslAddVramPrefixPtr(adr)
	Adds a VRAM prefix to an address.

#define	oslRemoveVramPrefixPtr(adr)
	Removes the VRAM prefix from an address.

Typedefs
typedef enum OSL_LOCATION_FLAGS	OSL_LOCATION_FLAGS
	Flags indicating the memory location of an image and optional swizzling.

Enumerations
enum	OSL_IMAGE_FLAGS { OSL_IMAGE_SWIZZLED = 1 , OSL_IMAGE_COPY = 2 , OSL_IMAGE_AUTOSTRIP = 4 }
	Constants for the flags member of OSL_IMAGE. More...

enum	OSL_LOCATION_FLAGS { OSL_IN_NONE = 0 , OSL_IN_VRAM = 1 , OSL_IN_RAM = 2 , OSL_LOCATION_MASK = 7 , OSL_SWIZZLED = 8 , OSL_UNSWIZZLED = 16 }
	Flags indicating the memory location of an image and optional swizzling. More...

enum	OSL_PIXELFORMATS { OSL_PF_5650 = GU_PSM_5650 , OSL_PF_5551 = GU_PSM_5551 , OSL_PF_4444 = GU_PSM_4444 , OSL_PF_8888 = GU_PSM_8888 , OSL_PF_4BIT = GU_PSM_T4 , OSL_PF_8BIT = GU_PSM_T8 }
	Pixel formats used for defining color modes in OSLib. More...

Functions
OSL_IMAGE *	oslCreateImage (int larg, int haut, short location, short pixelFormat)
	Creates an empty image in OSLib.

void	oslDeleteImage (OSL_IMAGE *img)
	Deletes an image previously created or loaded.

OSL_IMAGE *	oslLoadImageFile (char *filename, int location, int pixelFormat)
	Loads an image from a file, allowing selection of its location and pixel format.

OSL_IMAGE *	oslLoadImageFilePNG (char *filename, int location, int pixelFormat)
	Loads an image from a PNG file.

OSL_IMAGE *	oslLoadImageFileJPG (char *filename, int location, int pixelFormat)
	Loads an image from a JPG file.

OSL_IMAGE *	oslLoadImageFileGIF (char *filename, int location, int pixelFormat)
	Loads an image from a GIF file.

void *	oslAllocImageData (OSL_IMAGE *img, int location)
	Allocates memory for image data based on the properties of the provided OSL_IMAGE structure.

void	oslFreeImageData (OSL_IMAGE *img)
	Frees the memory allocated for image data.

int	oslImageLocationIsSwizzled (int location)
	Checks if an image location is swizzled.

Variables
int	osl_autoSwizzleImages
	Controls automatic swizzling of images.

int	osl_alignBuffer
	Controls advanced parameters for image creation.

Detailed Description

Image support in OSLib.

Macro Definition Documentation

◆ OSL_PALETTEDATA16

#define OSL_PALETTEDATA16 unsigned short __attribute__((aligned(16)))

Type definition for 16-bit palette data.

This type defines a 16-bit palette data structure with 16-byte alignment. It is used for handling image palettes in memory with proper alignment for performance optimization.

This type is typically used when working with image data that requires a palette of 16-bit entries.

@note The alignment ensures that the data structure is properly aligned in memory, which can be important for certain hardware optimizations.

◆ OSL_PALETTEDATA32

#define OSL_PALETTEDATA32 unsigned long __attribute__((aligned(16)))

Type definition for 32-bit palette data.

This type defines a 32-bit palette data structure with 16-byte alignment. It is used for handling image palettes in memory with proper alignment for performance optimization.

This type is typically used when working with image data that requires a palette of 32-bit entries.

@note The alignment ensures that the data structure is properly aligned in memory, which can be important for certain hardware optimizations.

◆ oslAddVramPrefixPtr

#define oslAddVramPrefixPtr ( adr )

Value:

((void *)((int)(adr) | 0x04000000))

Adds a VRAM prefix to an address.

This macro modifies an address by adding a VRAM prefix. It is used to convert a given address to its VRAM-mapped address by setting the appropriate prefix bit.

Parameters

adr	The original address to which the VRAM prefix will be added.

Returns: The address with the VRAM prefix added. The prefix is added by setting the highest bit of the address.

Example:

void *vramAddress = oslAddVramPrefixPtr(0x12345678);

oslAddVramPrefixPtr

#define oslAddVramPrefixPtr(adr)

Adds a VRAM prefix to an address.

Definition drawing.h:1275

This will result in vramAddress being 0x12345678 | 0x04000000.

◆ oslRemoveVramPrefixPtr

#define oslRemoveVramPrefixPtr ( adr )

Value:

((void *)((int)(adr) & (~0x04000000)))

Removes the VRAM prefix from an address.

This macro removes the VRAM prefix from an address. It is used to convert a VRAM-mapped address back to its original address by clearing the VRAM prefix bit.

Parameters

adr	The VRAM-mapped address from which the VRAM prefix will be removed.

Returns: The address with the VRAM prefix removed. The prefix is removed by clearing the highest bit of the address.

Example:

void *originalAddress = oslRemoveVramPrefixPtr(0x12345678 | 0x04000000);

oslRemoveVramPrefixPtr

#define oslRemoveVramPrefixPtr(adr)

Removes the VRAM prefix from an address.

Definition drawing.h:1294

This will result in originalAddress being 0x12345678.

Typedef Documentation

◆ OSL_LOCATION_FLAGS

typedef enum OSL_LOCATION_FLAGS OSL_LOCATION_FLAGS

Flags indicating the memory location of an image and optional swizzling.

This enumeration defines various flags used to specify where an image should be placed in memory (RAM or VRAM) and whether it should be swizzled or unswizzled. These flags are typically used in functions that load or manage images within OSLib.

@enum OSL_LOCATION_FLAGS
@param OSL_IN_NONE
    Indicates that the image does not exist or the location is not specified.
@param OSL_IN_VRAM
    Places the image in VRAM (Video RAM), typically used for faster rendering.
@param OSL_IN_RAM
    Places the image in RAM (main system memory), offering more flexibility but potentially slower access.
@param OSL_LOCATION_MASK
    A mask value that covers all potential locations, ensuring compatibility with future location types.
@param OSL_SWIZZLED
    Directly swizzles the image upon loading, optimizing it for certain types of texture mapping. Only works with specific `oslLoadImage[...]` functions.
@param OSL_UNSWIZZLED
    Forces the image to be loaded without swizzling, overriding default behavior in the `oslLoadImage[...]` functions.

Enumeration Type Documentation

◆ OSL_IMAGE_FLAGS

enum OSL_IMAGE_FLAGS

Constants for the flags member of OSL_IMAGE.

These constants define the flags that can be used to specify various attributes of an image in OSLib.

@enum OSL_IMAGE_FLAGS
@param OSL_IMAGE_SWIZZLED
    Indicates that the image is swizzled. Swizzling refers to a technique used to optimize texture access patterns.
@param OSL_IMAGE_COPY
    Indicates that the image is a copy of another image. This can be used to identify and manage image copies.
@param OSL_IMAGE_AUTOSTRIP
    Indicates that the image can be automatically stripped. This flag is used to manage automatic stripping operations on images.

Enumerator
OSL_IMAGE_SWIZZLED	Image is swizzled.
OSL_IMAGE_COPY	Image is a copy.
OSL_IMAGE_AUTOSTRIP	Image can be automatically stripped (let it one)

◆ OSL_LOCATION_FLAGS

enum OSL_LOCATION_FLAGS

Flags indicating the memory location of an image and optional swizzling.

This enumeration defines various flags used to specify where an image should be placed in memory (RAM or VRAM) and whether it should be swizzled or unswizzled. These flags are typically used in functions that load or manage images within OSLib.

@enum OSL_LOCATION_FLAGS
@param OSL_IN_NONE
    Indicates that the image does not exist or the location is not specified.
@param OSL_IN_VRAM
    Places the image in VRAM (Video RAM), typically used for faster rendering.
@param OSL_IN_RAM
    Places the image in RAM (main system memory), offering more flexibility but potentially slower access.
@param OSL_LOCATION_MASK
    A mask value that covers all potential locations, ensuring compatibility with future location types.
@param OSL_SWIZZLED
    Directly swizzles the image upon loading, optimizing it for certain types of texture mapping. Only works with specific `oslLoadImage[...]` functions.
@param OSL_UNSWIZZLED
    Forces the image to be loaded without swizzling, overriding default behavior in the `oslLoadImage[...]` functions.

Enumerator
OSL_IN_NONE	Doesn't exist.
OSL_IN_VRAM	In VRAM.
OSL_IN_RAM	In RAM.
OSL_LOCATION_MASK	There will probably never be more than 8 locations...
OSL_SWIZZLED	Directly swizzle image (only works for oslLoadImage[...] functions!)
OSL_UNSWIZZLED	Force no swizzling (oslLoadImage[...])

◆ OSL_PIXELFORMATS

enum OSL_PIXELFORMATS

Pixel formats used for defining color modes in OSLib.

This enumeration defines various pixel formats that are used to describe the color depth and layout of image data within OSLib. These formats are aligned with the PlayStation Portable (PSP) graphics engine's formats and are used for texture and image processing.

@enum OSL_PIXELFORMATS
@param OSL_PF_5650
16-bit format with 5 bits for the red, 6 bits for the green, and 5 bits for the blue components, with no alpha (transparency) channel.
This format corresponds to `GU_PSM_5650` in the PSP's graphics engine.
@param OSL_PF_5551
16-bit format with 5 bits for the red, 5 bits for the green, 5 bits for the blue components, and 1 bit for alpha (transparency).
This format corresponds to `GU_PSM_5551` in the PSP's graphics engine.
@param OSL_PF_4444
16-bit format with 4 bits each for the red, green, blue, and alpha components.
This format corresponds to `GU_PSM_4444` in the PSP's graphics engine.
@param OSL_PF_8888
32-bit format with 8 bits for each of the red, green, blue, and alpha components, allowing for a full range of colors and transparency.
This format corresponds to `GU_PSM_8888` in the PSP's graphics engine.
@param OSL_PF_4BIT
Paletted format with 4 bits per pixel, allowing for 16 different colors. This format is typically used with a palette and cannot be used as a drawbuffer.
It corresponds to `GU_PSM_T4` in the PSP's graphics engine.
@param OSL_PF_8BIT
Paletted format with 8 bits per pixel, allowing for 256 different colors. Like the 4-bit format, it is used with a palette and cannot be set as a drawbuffer.
It corresponds to `GU_PSM_T8` in the PSP's graphics engine.

Enumerator
OSL_PF_5650	16 bits, 5 bits per component, except green which has 6, no alpha
OSL_PF_5551	15 bits, 5 bits per component, 1 alpha bit
OSL_PF_4444	12 bits, 4 bits per component, 4 alpha bits
OSL_PF_8888	32 bits, 8 bits per component, 8 alpha bits
OSL_PF_4BIT	Paletted format, 4 bits (16 colors), cannot be set as drawbuffer.
OSL_PF_8BIT	Paletted format, 8 bits (256 colors), cannot be set as drawbuffer.

Function Documentation

◆ oslCreateImage()

OSL_IMAGE * oslCreateImage	(	int	larg,
		int	haut,
		short	location,
		short	pixelFormat )

extern

Creates an empty image in OSLib.

This function creates an empty image with specified dimensions, location, and pixel format. The image is initially filled with random values, so it's important to clear it using oslClearImage() before use.

Parameters

larg	Width of the image. The actual width will be aligned to the next power of two to ensure compatibility with the PSP's graphics system, and each image line will be aligned to at least 16 bytes.
haut	Height of the image. The actual height will be aligned to the next multiple of 8 to allow for swizzling operations.
location	Specifies the memory location for the image. It should be either `OSL_IN_VRAM` (Video RAM) or `OSL_IN_RAM` (system RAM).
pixelFormat	Defines the pixel format of the image, determining its color type, precision, and memory usage. While higher formats like `OSL_PF_8888` provide better image quality, they also consume more memory and may reduce rendering performance. It is advised to use lower formats where possible.

Returns: Returns a pointer to the created OSL_IMAGE. If the image creation fails, the function returns NULL. It's essential to check for a NULL return value to avoid crashes, as trying to use a NULL image will cause the PSP to shut down after a brief period.

Note

The maximum allowable size for an image is 512x512 pixels. Both the width and height must not exceed 512 pixels.
Empty images created using this function are not automatically swizzled, even if the oslSetImageAutoSwizzle parameter is enabled.
Do NOT pass OSL_SWIZZLED or OSL_UNSWIZZLED flags to oslCreateImage(); these flags are not applicable during image creation.

◆ oslDeleteImage()

void oslDeleteImage ( OSL_IMAGE * img )

extern

Deletes an image previously created or loaded.

This function frees the memory associated with an image that was created or loaded using OSLib. Once deleted, the image pointer should no longer be used, as it will point to invalid memory.

Parameters

img	A pointer to the `OSL_IMAGE` structure representing the image to be deleted. If `img` is `NULL`, the function does nothing.

Note: Ensure that you set the pointer to NULL after deletion to avoid accidental usage of the deleted image pointer.

◆ oslLoadImageFile()

OSL_IMAGE * oslLoadImageFile	(	char *	filename,
		int	location,
		int	pixelFormat )

extern

Loads an image from a file, allowing selection of its location and pixel format.

This function loads an image from a specified file, automatically handling the details of format detection and memory management based on the provided location and pixel format.

Parameters

filename	The path to the image file to be loaded. The function will automatically detect the image format based on the file extension.
location	The location where the image will be stored (e.g., OSL_IN_RAM or OSL_IN_VRAM). The location affects performance and memory usage.
pixelFormat	The pixel format for the image. This determines the color depth and memory usage of the loaded image.

Returns: Returns a pointer to an OSL_IMAGE structure representing the loaded image. If the image fails to load (e.g., due to an invalid file path or unsupported format), the function returns NULL.

Note: Always check if the returned image pointer is NULL before using it to avoid crashes. Display a user-friendly message if the image fails to load, advising the user to check their files.

Warning: Avoid using this general-purpose function whenever possible, as it includes support for all image formats, potentially increasing your application's size and memory usage. Instead, use specific loading routines like oslLoadImageFilePNG, oslLoadImageFileJPG, etc., to conserve RAM.; When loading any image, adhere to the considerations in oslCreateImage, such as the 512x512 size limit. Images exceeding these dimensions are not supported.

◆ oslLoadImageFilePNG()

OSL_IMAGE * oslLoadImageFilePNG	(	char *	filename,
		int	location,
		int	pixelFormat )

extern

Loads an image from a PNG file.

This function loads an image from a specified PNG file, allowing selection of the memory location and pixel format. It is optimized for PNG files and helps conserve memory by avoiding the inclusion of unnecessary image format support.

Parameters

filename	The path to the PNG file to be loaded.
location	The location where the image will be stored (e.g., OSL_IN_RAM or OSL_IN_VRAM). The location affects performance and memory usage.
pixelFormat	The pixel format for the image. This determines the color depth and memory usage of the loaded image.

Returns: Returns a pointer to an OSL_IMAGE structure representing the loaded PNG image. If the image fails to load (e.g., due to an invalid file path or unsupported format), the function returns NULL.

Note: Always check if the returned image pointer is NULL before using it to avoid crashes. Display a user-friendly message if the image fails to load, advising the user to check their files.

Warning: The same considerations that apply to oslLoadImageFile also apply here, including the 512x512 size limit and the importance of handling NULL pointers.

◆ oslLoadImageFileJPG()

OSL_IMAGE * oslLoadImageFileJPG	(	char *	filename,
		int	location,
		int	pixelFormat )

extern

Loads an image from a JPG file.

This function loads an image from a specified JPG file, with options to select the memory location and pixel format. It is optimized for JPG files, but the decompression is limited and may not support high-quality JPGs.

Parameters

filename	The path to the JPG file to be loaded.
location	The location where the image will be stored (e.g., OSL_IN_RAM or OSL_IN_VRAM). The location affects performance and memory usage.
pixelFormat	The pixel format for the image. This determines the color depth and memory usage of the loaded image.

Returns: Returns a pointer to an OSL_IMAGE structure representing the loaded JPG image. If the image fails to load (e.g., due to an invalid file path, unsupported format, or high-quality JPG), the function returns NULL.

Note: Always check if the returned image pointer is NULL before using it to avoid crashes. Display a user-friendly message if the image fails to load, advising the user to check their files.

Warning: The JPG decompressor in this function is simple and does not support JPG files with a quality factor higher than 90%. Loading such files may cause the function to crash. Ensure that users are aware of this limitation in your instructions.

See also: oslLoadImageFile

◆ oslLoadImageFileGIF()

OSL_IMAGE * oslLoadImageFileGIF	(	char *	filename,
		int	location,
		int	pixelFormat )

extern

Loads an image from a GIF file.

This function loads an image from a specified GIF file, with options to select the memory location and pixel format. Similar to other image loading functions, it automatically handles the necessary steps for loading the image, but with some limitations regarding the image size and format.

Parameters

filename	The path to the GIF file to be loaded.
location	The location where the image will be stored (e.g., OSL_IN_RAM or OSL_IN_VRAM). This affects the performance and memory usage of the loaded image.
pixelFormat	The pixel format for the image. This determines the color depth and memory usage of the loaded image.

Returns: Returns a pointer to an OSL_IMAGE structure representing the loaded GIF image. If the image fails to load, the function returns NULL.

Note: Always check if the returned image pointer is NULL before using it to avoid crashes. Display a user-friendly message if the image fails to load, advising the user to check their files.

See also: oslLoadImageFile

◆ oslAllocImageData()

void * oslAllocImageData	(	OSL_IMAGE *	img,
		int	location )

extern

Allocates memory for image data based on the properties of the provided OSL_IMAGE structure.

This function allocates the necessary memory for an image based on its size and pixel format as defined in the OSL_IMAGE structure. It should be called before accessing or manipulating the image data.

Parameters

img	Pointer to an `OSL_IMAGE` structure for which memory needs to be allocated.
location	Specifies the location where the image data should be allocated. Valid values are typically `OSL_IN_RAM` or `OSL_IN_VRAM`.

Returns: Returns a pointer to the allocated memory for the image data. If memory allocation fails, it may return NULL. Always check for NULL to avoid accessing invalid memory.

Important: Ensure that the image's data member is properly initialized before using it. This function only allocates memory and does not initialize the data.

See also: oslCreateImage for Images creation and oslFreeImageData for memory deallocation.

◆ oslFreeImageData()

void oslFreeImageData ( OSL_IMAGE * img )

extern

Frees the memory allocated for image data.

This function deallocates the memory previously allocated for an image's data. It should be called to release memory and prevent memory leaks when the image is no longer needed.

Parameters

img	Pointer to an `OSL_IMAGE` structure for which memory should be freed.

Important: After calling this function, the data member of the OSL_IMAGE structure becomes invalid. Ensure that the pointer is not used after memory has been freed.

See also: oslAllocImageData for memory allocation and oslCreateImage for Images creation.

◆ oslImageLocationIsSwizzled()

int oslImageLocationIsSwizzled ( int location )

extern

Checks if an image location is swizzled.

This function determines if the image located at a specific location is swizzled. Swizzling is a technique used to improve performance by rearranging image data in memory.

Parameters

location The location identifier of the image to check. This can be an address or flag indicating where the image is stored.

Returns: Returns a non-zero value if the image at the specified location is swizzled, and 0 if it is not.

Note: This function is intended for internal use and may be subject to change in future versions of OSLib. It is recommended to avoid using this function directly.

Variable Documentation

◆ osl_autoSwizzleImages

int osl_autoSwizzleImages

extern

Controls automatic swizzling of images.

This variable determines whether images are automatically swizzled upon loading. Swizzling optimizes memory access patterns for images in VRAM, enhancing performance during rendering.

If set to a non-zero value, images loaded by functions like oslLoadImageFile and its variants will be automatically swizzled if the location is in VRAM.
If set to zero, images will not be swizzled automatically.

Note: This variable is typically set internally by oslSetImageAutoSwizzle, but it can also be modified directly for custom control.

◆ osl_alignBuffer

int osl_alignBuffer

extern

Controls advanced parameters for image creation.

This parameter allows for advanced control over how image sizes are aligned when creating images. It is intended for internal or advanced use and might be subject to breaking changes in future versions.

You can set osl_alignBuffer to control the alignment of image sizes:

1: Align the image width (horizontal size) to the nearest power of two.
2: Align the image height (vertical size) to the nearest multiple of 8, which is required for proper swizzling.

The default value is 3, which applies both of the above alignments.

Warning: This parameter is intended for advanced use cases. Modifying it without understanding its implications may lead to unexpected behavior or compatibility issues.

See also: oslCreateImage for details on how Images sizes are handled.

Topics

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ OSL_PALETTEDATA16

◆ OSL_PALETTEDATA32

◆ oslAddVramPrefixPtr

◆ oslRemoveVramPrefixPtr

Typedef Documentation

◆ OSL_LOCATION_FLAGS

Enumeration Type Documentation

◆ OSL_IMAGE_FLAGS

◆ OSL_LOCATION_FLAGS

◆ OSL_PIXELFORMATS

Function Documentation

◆ oslCreateImage()

◆ oslDeleteImage()

◆ oslLoadImageFile()

◆ oslLoadImageFilePNG()

◆ oslLoadImageFileJPG()

◆ oslLoadImageFileGIF()

◆ oslAllocImageData()

◆ oslFreeImageData()

◆ oslImageLocationIsSwizzled()

Variable Documentation

◆ osl_autoSwizzleImages

◆ osl_alignBuffer