GXInitSpecularDirv

Syntax

#include <revolution/gx.h>

#define GXInitSpecularDirv(lo,vec) \
 (GXInitSpecularDir((lo), *(f32*)(vec), *((f32*)(vec)+1), *((f32*)(vec)+2))

Arguments

Return Values

None.

Description

This macro function sets the direction of a specular light in the light object using a vector. This direction is used when the light object is used as a specular light. The memory for the light object must be allocated by the application. This function does not load any hardware registers. To load a light object into a hardware light, use the GXLoadLightObjImm or GXLoadLightObjIndx function.

The coordinate space of the light normal should be consistent with a vertex normal transformed by a normal matrix. In other words, it should be transformed to view space. The direction vector must be normalized.

The half-angle vector, necessary for specular lighting, is automatically calculated from the input light direction (nx, ny, nz) by assuming the view vector as (0, 0, 1). If you specify the input direction vector as (0, 0, 1), the half-angle vector becomes zero (no lighting effect) because the two vector directions are identical.

Note: This function must be used if the light object is used as specular light. You can activate a channel for specular lighting by setting the GXAttnFn argument in GXSetChanCtrl to GX_AF_SPEC. Do use the GXInitLightDir or GXInitLightPos function to set a light object which will be used as a specular light. These functions will destroy any data set by the GXInitSpecularDir function.

In contrast to diffuse lights (including spotlights) that are considered local lights, a specular light is a parallel light (the specular light is so far away that all light rays oare perceived as parallel); only directional information can be specified. If you use a light object which is set by this function for diffuse light, it acts as a (pseudo) parallel diffuse light.

Example

You may set an array of f32 values as the vec vector.

// Using an array
f32  dir[3] = { 1.0f, 0.0f, 0.0f };
GXLightObj  myLightObj;

GXInitSpecularDirv( &myLightObj, dir );

You can also use a structure which contains three f32 members (like the matrix-vector library's Vec type).

// Using a structure
typedef structure
{
    f32  x, y, z;
} Vec;

Vec         dir = { 1.0F, 0.0F, 0.0F };
GXLightObj  myLightObj;

GXInitSpecularDirv( &myLightObj, &dir );

See Also

GXInitSpecularDir, GXLightObj Initialization Flow

Revision History

2006/03/01 Initial version.

CONFIDENTIAL