VIConfigure

Syntax

#include <revolution/vi.h>
#include <revolution/gx/GXStruct.h>

void VIConfigure(const GXRenderModeObj* rm);

Arguments

rm	Render Mode. The following is a description of the members of the structure handled by `VIConfigure`.
	viTVMode	Screen Mode.
	viTVMode	`VI_TVMODE_NTSC_DS` sets the NTSC double-strike mode. `VI_TVMODE_NTSC_INT` sets the NTSC interlaced mode. `VI_TVMODE_NTSC_PROG` sets the NTSC progressive mode. `VI_TVMODE_PAL_DS` sets the PAL double-strike mode. `VI_TVMODE_PAL_INT` sets the PAL interlaced mode. `VI_TVMODE_EURGB60_DS` sets the EURGB60 double-strike mode. `VI_TVMODE_EURGB60_INT` sets the EURGB60 interlaced mode. `VI_TVMODE_EURGB60_PROG` sets the EURGB60 progressive mode.
	viXOrigin	On-screen X position, in pixels.
	viYOrigin	On-screen Y position, in pixels.
	viWidth	Screen width, in pixels.
	xFBmode	External frame buffer mode. Takes one of the following values:
	xFBmode	`VI_XFBMODE_DF` sets the double-field frame buffer mode. `VI_XFBMODE_SF` sets the single-field frame buffer mode.
	xfbHeight	Height of the external frame buffer (XFB).
	fbWidth	Width of the external frame buffer (XFB).

Return Values

None.

Description

This function configures the TV screen and external frame buffer. The following members of the GXRenderModeObj structure are used in this function.

viTVmode, viXOrigin, viYOrigin, viWidth, fbWidth, xfbHeight, xFBmode

viXOrigin and viYOrigin specify a position on the TV screen. viWidth specifies the x-directional size of the screen. viTVmode specifies whether to set the screen to NTSC, PAL, or EURGB60 and whether the mode is double-strike, interlaced, or progressive. fbWidth and xfbHeight specify the size of the external frame buffer. xFBmode specifies whether the frame buffer is set for single-field or double-field. Here, the term "single-field frame buffer" indicates that the frame buffer contains the image of a single field, whereas "double-field buffer" indicates that the buffer contains the images of two consecutive fields.

Be aware that screen height does not have to be specified. This information is included in xfbHeight and xFBmode. If xFBmode is double-field, the screen height is the same as xfbHeight. If xFBmode is single-field, the screen height is twice that of xfbHeight.

The change does not take effect until VIFlush is called. For more details on when changes take effect, see the VIFlush function manual.

Pan information is cleared when VIConfigure is called. Call VIConfigurePan if it is necessary for pan settings to remain in effect.

Due to hardware restrictions, at least two fields need to elapse to switch modes safely when viTVmode has been changed. When using VIConfigure to change modes (especially TV mode), call VIConfigure, then call VIWaitForRetrace twice to make sure that changes are made safely.

A list of argument restrictions is given below.

To understand the restrictions on viXOrigin, viYOrigin, and viWidth, see section 6.1, "Render Mode Customization" in the Video Interface manual.
There is a restriction on the left edge (viXOrigin) and right edge (viXOrigin + viWidth) of a TV image.
viXOrigin <= 307 (NTSC/EURGB60), 300 (PAL)
viXOrigin + viWidth >= 307 (NTSC/EURGB60), 300 (PAL)
Screen height must always be an even number. This means that xfbHeight must be an even number in double-field frame buffer mode. (For single-field frame buffer mode, the screen height is always an even number because it is twice that of xfbHeight.)
xfbHeight must be set to an even number when xfbMode == VI_XFBMODE_DF.

Revision History

2008/04/08 Corrected a mention of MPAL that had escaped deletion.
2007/12/04 Deleted the description of MPAL.
2006/08/15 Added EURGB60 and MPAL progressive modes.
2006/03/01 Initial version.