Main
[Drawing]

Functions
void	oslInitGfx (int pixelFormat, int bDoubleBuffer)
void	oslStartDrawing ()
void	oslEndDrawing ()
void	oslSyncDrawing ()
void	oslSwapBuffers ()
void	oslEndGfx ()
void	oslSetSysDisplayListSize (int newSize)

---

Detailed Description

Main and configuration routines of the drawing part of OSLib.

---

Function Documentation

void oslInitGfx	(	int	pixelFormat,
		int	bDoubleBuffer
	)

Initializes the graphical part of OSLib.

Parameters:

	pixelFormat	Defines the screen resolution. OSL_PF_8888: 32-bit render, very precise and nice, especially when it comes to gradients. However requires twice the memory required by the 16-bit mode (1088 kilobytes in double buffer mode, half in single buffer mode). Also uses more bandwidth and thus is slower. OSL_PF_5650: 16-bit render, can only display 65 thousand colors instead of 16 millions. Requires 544 kB in double buffer mode, and half in single buffer mode. It's the recommended mode. Use oslSetDithering to simulate more colors with dithering.
	bDoubleBuffer	A game will always use double buffering (else flickering will appear), let it to TRUE (1) except if you really know what you are doing. Look at oslSwapBuffers for more information.

Note: you can call it as many times as you want. However, any images placed in video memory (OSL_IN_VRAM) will be invalidated after a call to oslInitGfx, so make sure to delete all of them before, else you'll encounter (very) weird and random problems!

void oslStartDrawing

(

)

Starts drawing with OSLib. Call this before trying to draw anything.

void oslEndDrawing

(

)

Ends drawing. Call this once you've finished your render. This command will wait for the GPU to finish its render, and thus can be slow. Though, OSLib can use this remaining time to render and output sound.

void oslSyncDrawing

(

)

oslSyncDrawing waits for the GPU (that's how I'm calling the graphic processor; some say GE, meaning Graphic Engine) rendering to finish. As rendering is done in parallel with the CPU, you may be modifying an image which is currently used by the GPU, and thus render will be incorrect. In this case you should first issue a oslSyncDrawing to be sure the GPU is not active anymore and modify what you want after that. Howerver, take note that synchronizing with the GPU waits that it ends everythings it's doing, and thus can be VERY slow, so avoid doing it except if you really need it and if you know what you are doing.

Note: The amount of things you can draw between a call to oslStartDrawing and oslEndDrawing is limited because commands are sent to the GPU, and they are stored in the so called display list, which has a limited size. If you overflow the display list size, your program will crash (or have very weird behaviour). oslSyncDrawing waits the GPU to finish to execute the display list and resets it to zero (as oslStartDrawing / oslEndDrawing do: oslSyncDrawing is just a faster way to call both one after the other, it just skips end and beginning of frame processes). So, if you are really drawing a lot of things at once and your program is crashing, try to put a oslSyncDrawing somewhere.

void oslSwapBuffers

(

)

Swaps buffers. In double buffering mode, call it once per frame. The utility of double buffering is to avoid flickering, because if you only have one buffer, the buffer displayed on the screen is the same which you are drawing to. And thus the screen will show everything you're making with the buffer! So let's say you first draw a sky and then a sprite over it, the user will first see the sky and the sprite flickering.

With double buffering though you have one buffer which is displayed, and another (hidden) you're drawing to. Once rendering to the hidden buffer is terminated, you can show it to the user: this is swapping buffers. The user will now see the hidden buffer (which is complete now) and the other buffer will now become hidden so that you can draw another frame to it, and so on.

void oslEndGfx

(

)

Ends the graphical part, releasing memory for the display list. All images placed in video memory (OSL_IN_VRAM) become invalid after calling this, so make sure to release ALL of them before! You will need to reload them after having called oslInitGfx again.

void oslSetSysDisplayListSize

(

int

newSize

)

Very advanced command which sets the display list size. Don't use it unless you know what you are doing. Default is 1 MB (megabyte). Don't forget to call oslStartDrawing after a call to this function before beginning to draw again.