Creating or loading images
[Images]

Functions
OSL_IMAGE *	oslCreateImage (int larg, int haut, short location, short pixelFormat)
void	oslDeleteImage (OSL_IMAGE *img)
OSL_IMAGE *	oslLoadImageFile (char *filename, int location, int pixelFormat)
OSL_IMAGE *	oslLoadImageFilePNG (char *filename, int location, int pixelFormat)
OSL_IMAGE *	oslLoadImageFileJPG (char *filename, int location, int pixelFormat)
OSL_IMAGE *	oslLoadImageFileGIF (char *filename, int location, int pixelFormat)
void	oslSetImageAutoSwizzle (int enabled)
Variables
int	osl_alignBuffer

---

Detailed Description

Creating or loading images in OSLib.

---

Function Documentation

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

Creates an empty image. Please note that the image is initially filled with random values, you should take care to clear it by yourself with oslClearImage!

Parameters:

	larg	Width of the image. The real image size will be aligned to the next power of two and so that an image line contains at least 16 bytes.
	haut	Height of the image. The real image height will be aligned to the next multiple of 8 to make swizzling possible.
	location	Location of the image (either OSL_IN_VRAM or OSL_IN_RAM)
	pixelFormat	Format of pixels on the image. The pixel format directly defines the color type, precision and the room taken by the image. Also, biggest images are drawn slower (same applies to writting when they're set as drawbuffer). So, avoid using OSL_PF_8888 because it takes a lot of room and is slower. But the render is nicer of course ;)

Returns:

The return is NULL if the image could not be created! Always check for a NULL pointer else your program will CRASH when you'll try to use that image! (the PSP will turn off by itself after ten seconds).

Important: The maximum size of an image is 512x512! None of the height or width can exceed 512 (for example 10x600 is invalid, 10x500 is okay). Note: Empty created images are never swizzled automatically, even though the oslSetImageAutoSwizzle parameter is true. Do NOT pass OSL_SWIZZLED or OSL_UNSWIZZLED to oslCreateImage!

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. You can select its location and pixel format, the rest is done automatically.

Don't forget to check if the returned image is NULL before using it! In this case, display a gentleful message to the user telling him he has not read the readme and put the wrong files :p

Important: Avoid using this function, as it will automatically detect the format depending on the file extension. This means support for ALL formats will be added to your code, weightening your application a lot! Use specific routines instead like oslLoadImageFilePNG, oslLoadImageFileJPG, etc. to spare some precious RAM space.

Important (bis): When loading any image, see considerations with oslCreateImage, they apply to loaded images as well (namely the 512x512 limit).

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

Loads a PNG file. Same remark as for oslLoadImageFile apply.

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

Loads a JPG file. Same remark as for oslLoadImageFile apply.

Note: The actual JPG decompressor is very simple, and doesn't support JPG files of a too high quality (it will crash in this case). Avoid using JPG files with a quality factor of more than 90%. Also, if you let users the choice of using JPG files, you should specify this limitation in your instructions.

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

Loads a GIF file. Same remark as for oslLoadImageFile apply.

void oslSetImageAutoSwizzle

(

int

enabled

)

[inline]

Controls whether the images should automatically be swizzled upon loading. You can specify OSL_UNSWIZZLED to get a raw image, which you can then access using the data member of the image. Enabled by default, but wasn't in the first versions of OSLib.

//Force loading image as unswizzled
oslLoadImageFilePNG("test.png", OSL_IN_RAM | OSL_UNSWIZZLED, OSL_PF_5551);
//Force swizzled
oslLoadImageFilePNG("test.png", OSL_IN_RAM | OSL_SWIZZLED, OSL_PF_5551);
//Will swizzle if osl_autoSwizzleImages is set to true.
oslLoadImageFilePNG("test.png", OSL_IN_RAM, OSL_PF_5551);

---

Variable Documentation

int osl_alignBuffer

Controls advanced parameters when creating an image. Don't use it or be prepared to an eventual breaking change in the future.

Add the following values:

• 1: Align the image sizes horizontally to a power of two
• 2: Align the vertical size to a multiple of 8 (mandatory for swizzling)

Default value: 3.