Image manipulation
[Images]


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

enum OSL_WRITE_FLAGS

Look at oslWriteImageFilePNG for more information.

Enumerator:

OSL_WRI_ALPHA

Writes the alpha channel of the image.

Function Documentation

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

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

Parameters:

	offsetX0	The starting x position of the image part to reference
	offsetX1	The ending x position of the image part to reference
	offsetY0	The starting y 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 will 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? I don't remember). However if you delete the original image, the new one will be unusable! If you try to draw it, corrupt data may appear, and if you try to write to it, your program may crash.

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, avoid the use of it. Another way to do it would be:

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

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

Same but you specify the width and height of the image part to be displayed instead of the box coordinates.

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

Converts an image to another pixel format (and places it to another location). The image may have moved, so you must not try to use the original image anymore but the returned image instead!

image = oslConvertImageTo(image, OSL_IN_RAM, OSL_PF_5551);

OSL_IMAGE* oslCreateImageCopy	(	OSL_IMAGE *	src,
		int	newLocation
	)

Creates a copy of an image. The image data is copied as well, so the returned image is a completely new instance, and both are not linked together.

OSL_IMAGE* oslCreateSwizzledImage	(	OSL_IMAGE *	src,
		int	newLocation
	)

Creates a copy of an image, just like oslCreateImageCopy, but new one will be swizzled.

void oslCopyImageTo	(	OSL_IMAGE *	imgDst,
		OSL_IMAGE *	imgSrc
	)

Copies an image to another (copies the image data). Both images must have the same format (width, height, pixelformat) else the copy will fail!

void oslSwizzleImage ( OSL_IMAGE * img )

Swizzles an image. A swizzled image is then drawn a lot faster, but the problem is that you cannot modify it then because it gets a special format. However you can still unswizzle it, but it's slow if you do it often.

Hint: You should always swizzle images stored in RAM. Use the OSL_SWIZZLED bit when loading them for more facility.

void oslUnswizzleImage ( OSL_IMAGE * img )

Does the exact opposite of oslSwizzleImage. Call this after your image has been swizzled to restore its original state and make it accessible for raw reading and writing.

void oslSwizzleImageTo	(	OSL_IMAGE *	imgDst,
		OSL_IMAGE *	imgSrc
	)

Swizzles imgSrc and writes the result to imgDst. Old and bad routine. Use oslSwizzleImage instead (swizzles a single image).

bool oslMoveImageTo	(	OSL_IMAGE *	img,
		int	newLocation
	)

Moves an image to a new location, which can be either OSL_IN_RAM or OSL_IN_VRAM.

void oslClearImage	(	OSL_IMAGE *	img,
		int	color
	)

Clears an image with a specific value. Color is the raw pixel value, and depends from the pixelformat. For example if the image is OSL_PF_4BIT, the color is a palette entry number. Or if it's OSL_PF_5551 it's a 15-bit color with alpha. Example:

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

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

Writes an image to a file. Same remark as oslLoadImageFile, avoid this because it will autodetect the file type depending on its extension, and thus include EVERY possible format. This adds unnecessary code to your project, rendering it very fat and wasting RAM.

Note: It is impossible to write a swizzled image. OSLib internally checks for that, and calling oslWriteImageFile with a swizzled image will do nothing. If your image is swizzled, you should first unswizzle it by calling oslUnswizzleImage.

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

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.

void oslResetImageProperties ( OSL_IMAGE * img )

Resets the properties of an image (position, image tile, angle, rotation center, stretching).

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

Draws srcImg to dstImg with being scaled.

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

Creates a scaled copy of an image.

Image manipulation [Images]

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation

Image manipulation
[Images]