Main

Functions
void	oslInitGfx (int pixelFormat, int bDoubleBuffer)
void	oslStartDrawing ()
	Initializes the drawing process with OSLib. Call this function before performing any drawing operations.
void	oslEndDrawing ()
void	oslSyncDrawing ()
void	oslSwapBuffers ()
void	oslEndGfx ()
void	oslSetSysDisplayListSize (int newSize)

Detailed Description

Core functions and configuration routines for drawing in OSLib.

Function Documentation

oslInitGfx()

void oslInitGfx ( int pixelFormat, int bDoubleBuffer )

extern

Initializes the graphical system for OSLib.

This function sets up the rendering environment, including screen resolution, double buffering, and various graphical settings. It can be called multiple times, but note that all images stored in video memory (OSL_IN_VRAM) will be invalidated after calling this function, so ensure you delete all such images beforehand to avoid unexpected behavior.

Parameters

pixelFormat

The pixel format for the screen. Options include: OSL_PF_8888: 32-bit color mode, providing high precision and smooth gradients. However, it requires twice the memory of the 16-bit mode (1088 kB in double buffer mode, half in single buffer mode) and is slower due to higher bandwidth usage. OSL_PF_5650: 16-bit color mode, limited to 65,000 colors instead of 16 million. It requires 544 kB in double buffer mode and half in single buffer mode. This is the recommended mode for most applications. You can enable dithering with oslSetDithering to simulate more colors.

bDoubleBuffer

Set to TRUE (1) to enable double buffering, which is recommended for games to prevent flickering. Refer to oslSwapBuffers for more information on double buffering.

oslStartDrawing()

void oslStartDrawing ( )

extern

Initializes the drawing process with OSLib. Call this function before performing any drawing operations.

This function sets up the necessary GPU state and ensures that drawing operations are properly initialized. It also resets the current texture and palette to null and starts a new command list for rendering.

Note

If drawing has already started, this function will do nothing.

The commented section related to intraFont initialization is left out because it could interfere with user applications. If you need specific matrix configurations, consider setting them in your application.

oslEndDrawing()

void oslEndDrawing ( )

extern

Ends drawing. Call this function once you've finished rendering. This command waits for the GPU to finish rendering, which can be slow. OSLib may use this remaining time to process and output sound.

oslSyncDrawing()

void oslSyncDrawing ( )

extern

Waits for the GPU (Graphics Processing Unit) to complete its current rendering tasks. Since rendering occurs in parallel with CPU operations, there is a risk of modifying an image that the GPU is still processing, leading to incorrect render output.

Calling oslSyncDrawing ensures that the GPU has finished its operations, allowing you to safely modify graphical data afterward. However, be aware that synchronizing with the GPU can be very slow, as it waits for the GPU to complete all pending tasks. Use this function only when absolutely necessary and when you fully understand its performance implications.

Note: The number of drawing commands you can issue between oslStartDrawing and oslEndDrawing is limited by the size of the display list, where these commands are stored before being sent to the GPU. If the display list overflows, your program may crash or exhibit erratic behavior.

oslSyncDrawing resets the display list after waiting for the GPU to complete rendering, similar to what oslStartDrawing and oslEndDrawing do. It is a faster alternative for syncing without initiating the end and start of a frame. If you encounter crashes due to extensive drawing commands, consider inserting a call to oslSyncDrawing to mitigate the issue.

oslSwapBuffers()

void oslSwapBuffers ( )

extern

Swaps the buffers.

In double buffering mode, this function should be called once per frame. Double buffering prevents flickering by maintaining two buffers: one that is displayed on the screen and one that is used for drawing. Once drawing is complete, the buffers are swapped, displaying the newly rendered frame and hiding the previous one for the next drawing operation.

oslEndGfx()

void oslEndGfx ( )

extern

Ends the graphical context, releasing memory used for the display list.

After calling this function, all images placed in video memory (OSL_IN_VRAM) become invalid. Ensure that you release ALL such images before calling this function, as they will need to be reloaded after initializing graphics again with oslInitGfx.

oslSetSysDisplayListSize()

void oslSetSysDisplayListSize ( int newSize )

extern

Sets the display list size.

Parameters

newSize

The new size of the display list in bytes.

Warning

This is an advanced command. The default size is 1 MB. Do not use this function unless you fully understand the implications. After calling this function, you must call oslStartDrawing before beginning to draw again.