GXSetPixelFmt

C Specification

#include <revolution/gx.h>

void GXSetPixelFmt(
GXPixelFmt    pix_fmt, 
GXZFmt16      z_fmt );

Arguments

pix_fmt

pixel format
Accepted values are:

Name	Pixel Format
`GX_PF_RGB8_Z24`	no anti-aliasing 8-bit for each RGB value, 24-bit Z value.
`GX_PF_RGBA6_Z24`	no anti-aliasing 6-bit for each RGBA value, 24-bit Z value.
`GX_PF_RGB565_Z16`	anti-aliasing RGB565, 16-bit Z value

When GX_PF_RGB565_Z16 is selected, anti-aliasing mode is turned on. It's off otherwise.

z_fmt

The compression type for the 16-bit Z format.
Accepted values are:

Name	Z format
`GX_ZC_LINEAR`	linear 16-bit
`GX_ZC_NEAR`	compressed format for smaller far/near ratios
`GX_ZC_MID`	compressed format for medium far/near ratios
`GX_ZC_FAR`	compressed format for large far/near ratios

This argument is ignored if a 24-bit Z format is selected.

Return Values

None.

Description

This function sets the format of pixels in the embedded frame buffer (EFB) internal to the graphics processor. It also controls the anti-aliasing (AA) mode.

There are two non-antialiased pix_fmt pixel formats, GX_PF_RGB8_Z24 and GX_PF_RGBA6_Z24. The EFB stride is 640 pixels. The non-antialiased EFB has 528 lines available.

When pix_fmt is GX_PF_RGB565_Z16, multi-sample anti-aliasing is enabled. In order to get the correct results, GXSetCopyFilter must also be called. The position of the subsamples and the anti-aliasing filter coefficients are set using GXSetCopyFilter. When anti-aliasing, three 16-bit color/Z samples are calculated for each pixel, and the total available number of pixels in the EFB is reduced by half (640 pixels x 264 lines).

GXSetPixelFmt also sets the compression type for 16-bit Z formats, which allows Z precision trade-offs within the range. The following guidelines apply:

a) far/near ratio <= 2^16, use GX_ZC_LINEAR
b) far/near ratio <= 2^18, use GX_ZC_NEAR
c) far/near ratio <= 2^20, use GX_ZC_MID
d) far/near ratio <= 2^24, use GX_ZC_FAR

It is always best to use as little compression as possible (choice a is least compressed, choice d is most compressed). Higher compression results in less precision. The far in the above list does not necessarily reference the far clipping plane. You should think of it as the farthest object that you want to have accurate occlusion.

Performance Notes

Since changing the pixel format requires the pixel pipeline to be synchronized, the use of this function causes the graphics processor to stall as a result. Therefore, redundant calls of this function should be avoided.

Revision History

03/01/2006 Initial version.