Drawbuffers

Macros
#define	oslGetDrawBuffer()   osl_curBuf
#define	OSL_DEFAULT_BUFFER   (&osl_defaultBufferImage)
#define	OSL_SECONDARY_BUFFER   (&osl_secondaryBufferImage)
#define	OSL_SCREEN_WIDTH   (osl_curBuf->sizeX)
#define	OSL_SCREEN_HEIGHT   (osl_curBuf->sizeY)

Enumerations
enum	OSL_FX_ALPHAWRITE { OSL_FXAW_NONE, OSL_FXAW_SET }
enum	OSL_FX_ALPHATEST

Functions
void	oslSetDrawBuffer (OSL_IMAGE *img)
void	oslSetAlphaWrite (int action, int value1, int value2)
void	oslSetAlphaTest (int condition, int value)
void	oslDisableAlphaTest ()

Variables
int	osl_alphaTestEnabled

Detailed Description

Drawbuffers is an advanced and powerful capability of OSLib images, it allows you to draw directly on an image exactly as if you were drawing on the screen! See oslSetDrawBuffer for basic a code sample.

Macro Definition Documentation

#define oslGetDrawBuffer

(

)

osl_curBuf

Returns the current drawbuffer as an OSL_IMAGE. You can save it to restore it later.

#define OSL_DEFAULT_BUFFER   (&osl_defaultBufferImage)

An image representing the primary buffer image, which is the buffer to which you are currently writing (see oslSwapBuffers for more information).

#define OSL_SECONDARY_BUFFER   (&osl_secondaryBufferImage)

An image representing the secondary buffer image, which is the buffer currently displayed to the user (see oslSwapBuffers for more information). In single buffering mode, OSL_DEFAULT_BUFFER is identical to OSL_SECONDARY_BUFFER.

#define OSL_SCREEN_WIDTH   (osl_curBuf->sizeX)

Returns the width of the current drawbuffer. On the default drawbuffer (i.e. the screen) it will be the resolution of the PSP LCD, that is 480 pixels. By taking these values in account you can make game that automatically adapt to another resolution.

#define OSL_SCREEN_HEIGHT   (osl_curBuf->sizeY)

Returns the height of the current drawbuffer. On the default drawbuffer (i.e. the screen) it will be the resolution of the PSP LCD, that is 272 pixels.

Enumeration Type Documentation

enum OSL_FX_ALPHAWRITE

Available effects for oslSetAlphaWrite.

Enumerator
OSL_FXAW_NONE	Does not write alpha.
OSL_FXAW_SET	Sets alpha to value1 if the alpha channel of the pixel is not equal to value2.

enum OSL_FX_ALPHATEST

Alpha test comparision operators. See oslSetAlphaTest.

Function Documentation

void oslSetDrawBuffer

(

OSL_IMAGE *

img

)

Define an image as the current drawbuffer. Don't forget to restore the original drawbuffer once you've finished drawing to the image. Here is an example that draws something on an image, and then draws that image on the real screen.

OSL_IMAGE *drawBuf = oslCreateImage(320, 182, OSL_IN_VRAM, OSL_PF_5650);
//Clear the image to black
oslClearImage(drawBuf, RGB16(0, 0, 0));
//We set that image as the drawbuffer
oslSetDrawBuffer(drawBuf);
//Draw a red filled rectangle on the image
oslDrawFillRect(0, 0, 100, 100, RGB(255, 0, 0));
//Restore the default drawbuffer
oslSetDrawBuffer(OSL_DEFAULT_BUFFER);
//Draw that image somewhere on the screen
oslDrawImageXY(drawBuf, 80, 45);

Important: The image pixel format must be non-paletted! (supported formats are 4444, 5551, 5650 and 8888). 8888 mode (32-bit) is slower than others and the image is bigger. Also, the image MUST be in video memory (OSL_IN_VRAM). The GPU can't write to regular RAM (it can only read from it).

A common problem is the image not being displayed because its alpha is null. You can temporarily disable alpha blending by calling oslSetAlpha(OSL_FX_NONE, 0) to prevent this problem, but the best solution is to not forget to always clear the image after you've created it!

void oslSetAlphaWrite	(	int	action,
		int	value1,
		int	value2
	)

Enables writing to the alpha channel of the drawbuffer. You won't care about it when using the standard drawbuffer, but when it comes to draw on an image, it may become important. By default, alpha values are never set on the drawbuffer (let as they are).

Parameters

action	OSL_FXAW_SET: Set the alpha to value1. Every pixel written to the drawbuffer will set the alpha value to value1. All pixels (for example from a square or rectangle image) will set the alpha value, even if they are transparent. In order to avoid this, you can set-up an alpha test which masks out transparents pixels. They will not be drawn and the alpha value will not be written in the drawbuffer.
value1	If action is OSL_FXAW_SET, this parameter holds the alpha opacity to be written, from 0 to 255 (0 = transparent, 255 = opaque).
value2	Not used, let it 0.

I've not got pure copy of the alpha values to work. If someone has already used it and wants to share his experience, it would be very nice.

//Clear image to transparent (alpha=0)
oslClearImage(buffer, RGBA(0, 0, 0, 0));
//Set it as drawbuffer
oslSetDrawBuffer(buffer);
//Every pixel written will take the value 255 (opaque)
oslSetAlphaWrite(OSL_FXAW_SET, 255, 0);
//But do not draw transparent pixels (only those greater than 0).
oslSetAlphaTest(OSL_FXAT_GREATER, 0);
[...]

void oslSetAlphaTest	(	int	condition,
		int	value
	)

Set alpha testing parameters. The test will be made against the alpha value of the pixel to be drawn. If the test passes, the pixel is written to the screen, else it is ignored. Note that pixels from a OSL_PF_5650 image do not initially contain alpha, but obviously it is automatically set to opaque (alpha = 255).

Parameters

condition

Condition for the test to pass. Can be one of the following: OSL_FXAT_NEVER: Never passes. OSL_FXAT_ALWAYS: Always passes. OSL_FXAT_EQUAL: Alpha is equal to value. OSL_FXAT_NOTEQUAL: Alpha is not equal to value. OSL_FXAT_LESS: Alpha is less than value. OSL_FXAT_LEQUAL: Alpha is less or equal to value. OSL_FXAT_GREATER: Alpha is greater than value. OSL_FXAT_GEQUAL: Alpha is greater or equal to value.

value

Reference value for comparision.

void oslDisableAlphaTest

(

)

Disables alpha testing.

Variable Documentation

int osl_alphaTestEnabled

Holds whether alpha testing is currently enabled.