Data Structures | Macros | Functions | Variables
General
Drawing

Data Structures

struct  OSL_ALPHA_PARAMS
 

Macros

#define oslResetScreenClipping()   oslSetScreenClipping(0, 0, osl_curBuf->sizeX, osl_curBuf->sizeY);
 

Functions

void oslClearScreen (int backColor)
 
void oslSetScreenClipping (int x0, int y0, int x1, int y1)
 
void oslSetDepthTest (int enabled)
 
void oslSetAlpha2 (u32 effect, u32 coeff1, u32 coeff2)
 
void oslSetAlpha (u32 effect, u32 coeff1)
 
void oslGetAlphaEx (OSL_ALPHA_PARAMS *alpha)
 
void oslSetAlphaEx (OSL_ALPHA_PARAMS *alpha)
 
void oslSetBilinearFilter (int enabled)
 
void oslSetDithering (int enabled)
 
void oslSetTransparentColor (OSL_COLOR color)
 

Variables

int osl_bilinearFilterEnabled
 
int osl_ditheringEnabled
 
int osl_colorKeyEnabled
 

Detailed Description

General drawing tasks.

Macro Definition Documentation

#define oslResetScreenClipping ( )    oslSetScreenClipping(0, 0, osl_curBuf->sizeX, osl_curBuf->sizeY);

Resets the screen clipping to the whole screen.

Function Documentation

void oslClearScreen ( int  backColor)

Clears the entire screen with the specified color.

Parameters
backColorColor to fill the screen with.
void oslSetScreenClipping ( int  x0,
int  y0,
int  x1,
int  y1 
)

Sets the clipping region. Anything outside of the clipping rectangle will not be drawn on the screen. Initially the clipping region is set to the entire screen.

Note: oslSetDrawBuffer automatically adjusts the clipping region to cover the full the drawbuffer image.

void oslSetDepthTest ( int  enabled)

Sets the depth test.

void oslSetAlpha2 ( u32  effect,
u32  coeff1,
u32  coeff2 
)

Sets current special alpha effect parameters. Images and shapes drawn next to this command will be using these parameters.

Parameters
effectCan be one of the following:
  • OSL_FX_NONE: Blending is purely disabled.
  • OSL_FX_DEFAULT: Reverts to default mode (RGBA).
  • OSL_FX_RGBA: The alpha value of images or colors is taken in account for blending. For example, drawing a rectangle with the following color: RGBA(0, 0, 0, 128) will draw it semi-transparent.
  • OSL_FX_ALPHA: Regular alpha blending: dstColor = dstColor = srcColor * coeff1 + dstColor * (1 - coeff1).
  • OSL_FX_ADD: Color addition: dstColor = dstColor * coeff2 + srcColor * coeff1. With oslSetAlpha, coeff2 is not supplied and set to full (255) by default.
  • OSL_FX_SUB: Color substraction: dstColor = dstColor * coeff2 - srcColor * coeff1. Please note that substracting colors produce the invert effect that you'd expect to see: substracting red (255, 0, 0) from a white image (255, 255, 255) for example gives cyan output (0, 255, 255). Furthermore, you can OR the value with the following:
  • OSL_FX_COLOR: Coeff1 and coeff2 are treated as 32-bit colors instead of 8-bit alpha values. Multiplication between a color and another gives a tinted color.
coeff1Coefficient used in the operations described above. Either alpha coefficient (0 to 255) or color (0 to 0xffffffff)
coeff2Extended coefficient used in the operations described above.

Here are some examples:

//Default alpha
oslSetAlpha(OSL_FX_DEFAULT, 0);
//Tint an image with red
oslSetAlpha(OSL_FX_TINT, RGBA(255, 0, 0, 255));
//The image will be drawn semi-transparent.
oslSetAlpha(OSL_FX_ALPHA, 128);
//Tinted + semi-transparent image
oslSetAlpha(OSL_FX_ALPHA | OSL_FX_COLOR, RGBA(255, 0, 0, 128));
//Simple addition as on the Super Nintendo
oslSetAlpha(OSL_FX_ADD, 255);
//dst = 0.5 * src + 0.5 * dst
oslSetAlpha2(OSL_FX_ADD, 128, 128);

That's not all, a lot of nice effects can be produced with this function.

About multiplication, note that black won't be tinted as it's a multiplication, zero * something always gives zero. In fact, a multiplication always gives a darker color. Each separate color component is first divided by 255 and then multiplicated with the other one. For example, let's multiply gray RGB(128, 128, 128) by orange RGB(255, 128, 0):

  • r1 is 128 (red for the first component)
  • g1 is 128 (green for the first component)
  • b1 is 128 (...)
  • r2 is 255 (red for the second component)
  • g2 is 128 (...)
  • b2 is 0

By ranging them to 1.0, we get r1 =0.5, g1 = 0.5, b1 = 0.5, r2 = 1.0, g2 = 0.5, b2 = 0.0. We now multiply r1 by r2, g1 by g2 and b1 by b2. The final result is: RGB(0.5, 0.25, 0.0), which is, when converted again RGB(128, 64, 0), brown! In general, multiplicating by gray always darkens the color, multiplying by white does nothing, and multiplying by black gives black. You can get some nice effects once you've understood correctly what color operations do.

void oslSetAlpha ( u32  effect,
u32  coeff1 
)
inline

See oslSetAlpha2.

void oslGetAlphaEx ( OSL_ALPHA_PARAMS *  alpha)
inline

Stores the current alpha parameters to an OSL_ALPHA_PARAMS structure.

void oslSetAlphaEx ( OSL_ALPHA_PARAMS *  alpha)
inline

Sets the current alpha parameters using an OSL_ALPHA_PARAMS structure.

void oslSetBilinearFilter ( int  enabled)

Enables (1) or disables (0) bilinear filtering.

Bilinear filtering "smoothes" images, reducing the edge aliasing when you stretch or rotate them. However for text and unstretched images, smoothing creates a blurry effect, so avoid enabling it permanently.

void oslSetDithering ( int  enabled)

Enables (1) or disables (0) dithering. If you are using the 16-bit mode (as specified with oslInitGfx) or you are drawing to a 16-bit image, you can enable dithering. If a color can't be rendered exactly, it will use the nearest available colors and blend them together (with small dots) to give the illusion of an intermediate color. For example, dithering red and yellow gives the illusion of an orange surface.

void oslSetTransparentColor ( OSL_COLOR  color)

Enables color keying. Any pixel of the specified color will not be drawn to the screen.

It has not much interest in itself, but the fact is that it takes effect as well when loading images. Any color equal to this one is set as transparent. As transparency is defined by the alpha channel, you can disable color keying then and the image will still contain transparency.

Example 1: loading an image with a color key. You can often see that the background of some sprite images are of a bright and unconventional color, like pink or bright red. This color is not used usually, but is only there to define the transparent parts of the image. Our example uses bright pink as a transparent color:

//Bright pink pixels will be transparent
oslSetTransparentColor(RGB(255, 0, 255));
//Load the image. Take care to select a pixel format which contains alpha. Every pixel format does, except 5650.
OSL_IMAGE *img = oslLoadImageFilePNG("test.png", OSL_IN_RAM, OSL_PF_5551);
//Load some other images, with pink as transparent...
//After loading images, disable color keying else we won't be able to display any pink pixels, and the render will appear messed up...
oslDisableTransparentColor();

Example 2: Enable this when drawing (as said, it has nearly no interest in itself):

oslSetTransparentColor(RGB(255, 0, 255));
//You'd expect this command to do something? In fact it won't as the rectangle is pink and pink is currently masked out...
oslDrawFillRect(0, 0, 100, 100, RGB(255, 0, 255));

Variable Documentation

int osl_bilinearFilterEnabled

Holds whether bilinear filetering is currently turned on.

int osl_ditheringEnabled

Holds whether dithering is currently turned on.

int osl_colorKeyEnabled

Holds whether color keying is enabled.