QuesaLight.h

Discussion

Declares the Quesa light objects.

Functions

Q3AmbientLight_GetData

( TQ3Status ) Q3AmbientLight_GetData (
    TQ3LightObject light,
    TQ3LightData *lightData
);

Discussion

Get the data for an ambient light.

Parameter Descriptions

light
The light to query.

lightData
Receives the data of the light.

function result: Success or failure of the operation.

Q3AmbientLight_New

( TQ3LightObject ) Q3AmbientLight_New (
    const TQ3LightData *lightData
);

Discussion

Create a new ambient light object.

Parameter Descriptions

lightData
The data for the light object.

function result: The new light object.

Q3AmbientLight_SetData

( TQ3Status ) Q3AmbientLight_SetData (
    TQ3LightObject light,
    const TQ3LightData *lightData
);

Discussion

Set the data for an ambient light.

Parameter Descriptions

light
The light to update.

lightData
The new data for the light.

function result: Success or failure of the operation.

Q3DirectionalLight_GetCastShadowsState

( TQ3Status ) Q3DirectionalLight_GetCastShadowsState (
    TQ3LightObject light,
    TQ3Boolean *castsShadows
);

Discussion

Get the cast-shadow state of a directional light.

Parameter Descriptions

light
The light to query.

castsShadows
Receives true or false as the light casts shadows.

function result: Success or failure of the operation.

Q3DirectionalLight_GetData

( TQ3Status ) Q3DirectionalLight_GetData (
    TQ3LightObject light,
    TQ3DirectionalLightData *directionalLightData
);

Discussion

Get the data for a directional light.

Parameter Descriptions

light
The light to query.

directionalLightData
Receives the data of the light.

function result: Success or failure of the operation.

Q3DirectionalLight_GetDirection

( TQ3Status ) Q3DirectionalLight_GetDirection (
    TQ3LightObject light,
    TQ3Vector3D *direction
);

Discussion

Get the direction of a directional light.

Parameter Descriptions

light
The light to query.

direction
Receives the direction of the light.

function result: Success or failure of the operation.

Q3DirectionalLight_New

( TQ3LightObject ) Q3DirectionalLight_New (
    const TQ3DirectionalLightData *directionalLightData
);

Discussion

Create a new directional light object.

Parameter Descriptions

directionalLightData
The data for the light object.

function result: The new light object.

Q3DirectionalLight_SetCastShadowsState

( TQ3Status ) Q3DirectionalLight_SetCastShadowsState (
    TQ3LightObject light,
    TQ3Boolean castsShadows
);

Discussion

Set the cast-shadow state of a directional light.

Parameter Descriptions

light
The light to update.

castsShadows
True or false as the light casts shadows.

function result: Success or failure of the operation.

Q3DirectionalLight_SetData

( TQ3Status ) Q3DirectionalLight_SetData (
    TQ3LightObject light,
    const TQ3DirectionalLightData *directionalLightData
);

Discussion

Set the data for a directional light.

Parameter Descriptions

light
The light to update.

directionalLightData
The new data for the light.

function result: Success or failure of the operation.

Q3DirectionalLight_SetDirection

( TQ3Status ) Q3DirectionalLight_SetDirection (
    TQ3LightObject light,
    const TQ3Vector3D *direction
);

Discussion

Set the direction of a directional light.

Parameter Descriptions

light
The light to update.

direction
The new direction for the light.

function result: Success or failure of the operation.

Q3Light_GetBrightness

( TQ3Status ) Q3Light_GetBrightness (
    TQ3LightObject light,
    float *brightness
);

Discussion

Get the brightness of a light.

Parameter Descriptions

light
The light to query.

brightness
Receives the brightness of the light.

function result: Success or failure of the operation.

Q3Light_GetColor

( TQ3Status ) Q3Light_GetColor (
    TQ3LightObject light,
    TQ3ColorRGB *color
);

Discussion

Get the color of a light.

Parameter Descriptions

light
The light to query.

color
Receives the color of the light.

function result: Success or failure of the operation.

Q3Light_GetData

( TQ3Status ) Q3Light_GetData (
    TQ3LightObject light,
    TQ3LightData *lightData
);

Discussion

Get the common state of a light.

Parameter Descriptions

light
The light to query.

lightData
Receives the common state of the light.

function result: Success or failure of the operation.

Q3Light_GetState

( TQ3Status ) Q3Light_GetState (
    TQ3LightObject light,
    TQ3Boolean *isOn
);

Discussion

Get the on/off state of a light.

Parameter Descriptions

light
The light to query.

isOn
Receives true/false as the light is on.

function result: Success or failure of the operation.

Q3Light_GetType

( TQ3ObjectType ) Q3Light_GetType (
    TQ3LightObject light
);

Discussion

Get the type of a light.

Returns kQ3ObjectTypeInvalid if the light type is unknown.

Parameter Descriptions

light
The light to query.

function result: The type of the light object.

Q3Light_SetBrightness

( TQ3Status ) Q3Light_SetBrightness (
    TQ3LightObject light,
    float brightness
);

Discussion

Set the brightness of a light.

Parameter Descriptions

light
The light to update.

brightness
The new brightness for the light.

function result: Success or failure of the operation.

Q3Light_SetColor

( TQ3Status ) Q3Light_SetColor (
    TQ3LightObject light,
    const TQ3ColorRGB *color
);

Discussion

Set the color of a light.

Parameter Descriptions

light
The light to update.

color
The new color for the light.

function result: Success or failure of the operation.

Q3Light_SetData

( TQ3Status ) Q3Light_SetData (
    TQ3LightObject light,
    const TQ3LightData *lightData
);

Discussion

Set the common state for a light.

Parameter Descriptions

light
The light to update.

lightData
The new common state for the light.

function result: Success or failure of the operation.

Q3Light_SetState

( TQ3Status ) Q3Light_SetState (
    TQ3LightObject light,
    TQ3Boolean isOn
);

Discussion

Set the on/off state for a light.

Parameter Descriptions

light
The light to update.

isOn
True or false as the light is on.

function result: Success or failure of the operation.

Q3PointLight_GetAttenuation

( TQ3Status ) Q3PointLight_GetAttenuation (
    TQ3LightObject light,
    TQ3AttenuationType *attenuation
);

Discussion

Get the attenuation of a point light.

Parameter Descriptions

light
The light to query.

attenuation
Receives the attenuation of the light.

function result: Success or failure of the operation.

Q3PointLight_GetCastShadowsState

( TQ3Status ) Q3PointLight_GetCastShadowsState (
    TQ3LightObject light,
    TQ3Boolean *castsShadows
);

Discussion

Get the cast-shadow state of a point light.

Parameter Descriptions

light
The light to query.

castsShadows
Receives true or false as the light casts shadows.

function result: Success or failure of the operation.

Q3PointLight_GetData

( TQ3Status ) Q3PointLight_GetData (
    TQ3LightObject light,
    TQ3PointLightData *pointLightData
);

Discussion

Get the data for a point light.

Parameter Descriptions

light
The light to query.

pointLightData
Receives the data of the light.

function result: Success or failure of the operation.

Q3PointLight_GetLocation

( TQ3Status ) Q3PointLight_GetLocation (
    TQ3LightObject light,
    TQ3Point3D *location
);

Discussion

Get the location of a point light.

Parameter Descriptions

light
The light to query.

location
Receives the location of the light.

function result: Success or failure of the operation.

Q3PointLight_GetRadius

( TQ3Status ) Q3PointLight_GetRadius (
    TQ3LightObject light,
    TQ3Float32 *radius
);

Discussion

Get the radius of a point light. By default, a point light has a radius of zero, but to achieve a fuzzy borders of shadows using certain renderers (ray tracers), you can set a radius on the light. The unit is related with the scale of the scene.

Parameter Descriptions

light
The light to query.

radius
Receives the radius of the light.

function result: Success or failure of the operation.

Q3PointLight_New

( TQ3LightObject ) Q3PointLight_New (
    const TQ3PointLightData *pointLightData
);

Discussion

Create a new point light object.

Parameter Descriptions

pointLightData
The data for the light object.

function result: The new light object.

Q3PointLight_SetAttenuation

( TQ3Status ) Q3PointLight_SetAttenuation (
    TQ3LightObject light,
    TQ3AttenuationType attenuation
);

Discussion

Set the attenuation of a point light.

Parameter Descriptions

light
The light to update.

attenuation
The new attenuation for the light.

function result: Success or failure of the operation.

Q3PointLight_SetCastShadowsState

( TQ3Status ) Q3PointLight_SetCastShadowsState (
    TQ3LightObject light,
    TQ3Boolean castsShadows
);

Discussion

Set the cast-shadow state of a point light.

Parameter Descriptions

light
The light to update.

castsShadows
True or false as the light casts shadows.

function result: Success or failure of the operation.

Q3PointLight_SetData

( TQ3Status ) Q3PointLight_SetData (
    TQ3LightObject light,
    const TQ3PointLightData *pointLightData
);

Discussion

Set the data for a point light.

Parameter Descriptions

light
The light to update.

pointLightData
The new data for the light.

function result: Success or failure of the operation.

Q3PointLight_SetLocation

( TQ3Status ) Q3PointLight_SetLocation (
    TQ3LightObject light,
    const TQ3Point3D *location
);

Discussion

Set the location of a point light.

Parameter Descriptions

light
The light to update.

location
The new location for the light.

function result: Success or failure of the operation.

Q3PointLight_SetRadius

( TQ3Status ) Q3PointLight_SetRadius (
    TQ3LightObject light,
    TQ3Float32 radius
);

Discussion

Set the radius of a point light. By default, a point light has a radius of zero, but to achieve a fuzzy borders of shadows using certain renderers (ray tracers), you can set a radius on the light. The unit is related with the scale of the scene.

Parameter Descriptions

light
The light to update.

attenuation
The new radius for the light.

function result: Success or failure of the operation.

Q3SpotLight_GetAttenuation

( TQ3Status ) Q3SpotLight_GetAttenuation (
    TQ3LightObject light,
    TQ3AttenuationType *attenuation
);

Discussion

Get the attenuation of a spot light.

Parameter Descriptions

light
The light to query.

attenuation
Receives the attenuation of the light.

function result: Success or failure of the operation.

Q3SpotLight_GetCastShadowsState

( TQ3Status ) Q3SpotLight_GetCastShadowsState (
    TQ3LightObject light,
    TQ3Boolean *castsShadows
);

Discussion

Get the cast-shadow state of a spot light.

Parameter Descriptions

light
The light to query.

castsShadows
Receives true or false as the light casts shadows.

function result: Success or failure of the operation.

Q3SpotLight_GetData

( TQ3Status ) Q3SpotLight_GetData (
    TQ3LightObject light,
    TQ3SpotLightData *spotLightData
);

Discussion

Get the data for a spot light.

Parameter Descriptions

light
The light to query.

spotLightData
Receives the data of the light.

function result: Success or failure of the operation.

Q3SpotLight_GetDirection

( TQ3Status ) Q3SpotLight_GetDirection (
    TQ3LightObject light,
    TQ3Vector3D *direction
);

Discussion

Get the direction of a spot light.

Parameter Descriptions

light
The light to query.

direction
Receives the direction of the light.

function result: Success or failure of the operation.

Q3SpotLight_GetFallOff

( TQ3Status ) Q3SpotLight_GetFallOff (
    TQ3LightObject light,
    TQ3FallOffType *fallOff
);

Discussion

Get the fall off of a spot light.

Parameter Descriptions

light
The light to query.

fallOff
Receives the fall off value of the light.

function result: Success or failure of the operation.

Q3SpotLight_GetHotAngle

( TQ3Status ) Q3SpotLight_GetHotAngle (
    TQ3LightObject light,
    float *hotAngle
);

Discussion

Get the hot angle of a spot light.

Parameter Descriptions

light
The light to query.

hotAngle
Receives the hot angle of the light.

function result: Success or failure of the operation.

Q3SpotLight_GetLocation

( TQ3Status ) Q3SpotLight_GetLocation (
    TQ3LightObject light,
    TQ3Point3D *location
);

Discussion

Get the location of a spot light.

Parameter Descriptions

light
The light to query.

location
Receives the location of the light.

function result: Success or failure of the operation.

Q3SpotLight_GetOuterAngle

( TQ3Status ) Q3SpotLight_GetOuterAngle (
    TQ3LightObject light,
    float *outerAngle
);

Discussion

Get the outer angle of a spot light.

Parameter Descriptions

light
The light to query.

outerAngle
Receives the outer angle of the light.

function result: Success or failure of the operation.

Q3SpotLight_New

( TQ3LightObject ) Q3SpotLight_New (
    const TQ3SpotLightData *spotLightData
);

Discussion

Create a new spot light object.

Parameter Descriptions

spotLightData
The data for the light object.

function result: The new light object.

Q3SpotLight_SetAttenuation

( TQ3Status ) Q3SpotLight_SetAttenuation (
    TQ3LightObject light,
    TQ3AttenuationType attenuation
);

Discussion

Set the attenuation for a spot light.

Parameter Descriptions

light
The light to update.

attenuation
The new attenuation for the light.

function result: Success or failure of the operation.

Q3SpotLight_SetCastShadowsState

( TQ3Status ) Q3SpotLight_SetCastShadowsState (
    TQ3LightObject light,
    TQ3Boolean castsShadows
);

Discussion

Set the cast-shadow state of a spot light.

Parameter Descriptions

light
The light to update.

castsShadows
True or false as the light casts shadows.

function result: Success or failure of the operation.

Q3SpotLight_SetData

( TQ3Status ) Q3SpotLight_SetData (
    TQ3LightObject light,
    const TQ3SpotLightData *spotLightData
);

Discussion

Set the data for a spot light.

Parameter Descriptions

light
The light to update.

spotLightData
The new data for the light.

function result: Success or failure of the operation.

Q3SpotLight_SetDirection

( TQ3Status ) Q3SpotLight_SetDirection (
    TQ3LightObject light,
    const TQ3Vector3D *direction
);

Discussion

Set the direction of a spot light.

Parameter Descriptions

light
The light to update.

direction
The new direction for the light.

function result: Success or failure of the operation.

Q3SpotLight_SetFallOff

( TQ3Status ) Q3SpotLight_SetFallOff (
    TQ3LightObject light,
    TQ3FallOffType fallOff
);

Discussion

Set the fall off of a spot light.

Parameter Descriptions

light
The light to update.

fallOff
The new fall off value for the light.

function result: Success or failure of the operation.

Q3SpotLight_SetHotAngle

( TQ3Status ) Q3SpotLight_SetHotAngle (
    TQ3LightObject light,
    float hotAngle
);

Discussion

Set the hot angle of a spot light.

Parameter Descriptions

light
The light to update.

hotAngle
The new hot angle for the light.

function result: Success or failure of the operation.

Q3SpotLight_SetLocation

( TQ3Status ) Q3SpotLight_SetLocation (
    TQ3LightObject light,
    const TQ3Point3D *location
);

Discussion

Set the location for a spot light.

Parameter Descriptions

light
The light to update.

location
The new location for the light.

function result: Success or failure of the operation.

Q3SpotLight_SetOuterAngle

( TQ3Status ) Q3SpotLight_SetOuterAngle (
    TQ3LightObject light,
    float outerAngle
);

Discussion

Set the outer angle of a spot light.

Parameter Descriptions

light
The light to update.

outerAngle
The new outer angle for the light.

function result: Success or failure of the operation.

Structs

TQ3DirectionalLightData

typedef struct TQ3DirectionalLightData {
    TQ3LightData                                lightData;
    TQ3Boolean                                  castsShadows;
    TQ3Vector3D                                 direction;
} TQ3DirectionalLightData;

Discussion

Describes the state for a directional light.

A directional light is defined by a vector, which indicates the world-space direction away from the light source.

Field Descriptions

lightData
The common state for the light.

castsShadows
Indicates if the light casts shadows.

direction
The direction of the light.

TQ3LightData

typedef struct TQ3LightData {
    TQ3Boolean                                  isOn;
    float                                       brightness;
    TQ3ColorRGB                                 color;
} TQ3LightData;

Discussion

Describes the common state for a light.

The common light state includes the on/off state, brightness, and color. Brightness and color values should be between 0.0 and 1.0 inclusive.

Some renderers may support over-saturated lights (where the brightness value is greater than 1.0), or even negative brightness (where the value is less than 0.0).

The effect of such brightness values is renderer-specific, and may result in kQ3NoticeBrightnessGreaterThanOne or kQ3NoticeBrightnessLessThanZero warnings.

Field Descriptions

isOn
Controls if the light is active or not.

brightness
The brightness of the light.

color
The colour of the light.

TQ3PointLightData

typedef struct TQ3PointLightData {
    TQ3LightData                                lightData;
    TQ3Boolean                                  castsShadows;
    TQ3AttenuationType                          attenuation;
    TQ3Point3D                                  location;
} TQ3PointLightData;

Discussion

Describes the state for a point light.

A point light is defined by a coordinate in world space, and an attenuation value which controls how the light diminishes with distance.

Field Descriptions

lightData
The common state for the light.

castsShadows
Indicates if the light casts shadows.

attenuation
The attenuation style of the light.

location
The location of the light.

TQ3SpotLightData

typedef struct TQ3SpotLightData {
    TQ3LightData                                lightData;
    TQ3Boolean                                  castsShadows;
    TQ3AttenuationType                          attenuation;
    TQ3Point3D                                  location;
    TQ3Vector3D                                 direction;
    float                                       hotAngle;
    float                                       outerAngle;
    TQ3FallOffType                              fallOff;
} TQ3SpotLightData;

Discussion

Describes the state for a spot light.

A spot light is defined by a coordinate in world space, a vector away from that coordinate, and an attenuation value which controls how the light diminishes with distance.

A spot light casts a cone of light, where the cone is defined by two angles. The hot angle is the angle from the center of the light cone to the point where the light intensity starts to drop, and the outerAngle is the angle from the center of the light to the point where the light intensity has fallen to zero.

The way the light intensity diminishes between the hotAngle and outerAngle values is controlled by the light fallOff value.

Both hotAngle and outerAngle are half-angles from the center of the light cone, and are specified in radians. They both range from 0.0 to kQ3Pi/2.0 (inclusive), and the outerAngle must be equal than or greater to the hotAngle.

Field Descriptions

lightData
The common state for the light.

castsShadows
Indicates if the light casts shadows.

attenuation
The attenuation style of the light.

location
The location of the light.

direction
The direction of the light.

hotAngle
The half-angle where the light intensity starts to drop.

outerAngle
The half-angle where the light intensity reaches zero.

fallOff
The fall off between the hotAngle and the outerAngle.

Enumerations

TQ3AttenuationType

typedef enum {
    kQ3AttenuationTypeNone                      = 0,
    kQ3AttenuationTypeInverseDistance           = 1,
    kQ3AttenuationTypeInverseDistanceSquared    = 2,
    kQ3AttenuationTypeSize32                    = 0xFFFFFFFF
} TQ3AttenuationType;

Discussion

Light attenuation methods.

The attenuation of a light controls how the intensity of the light is diminished over distance. In the real world, the itensity of a light source is attenuated as 1/(d*d).

Constants

kQ3AttenuationTypeNone
Intensity is not attenuated.

kQ3AttenuationTypeInverseDistance
Intensity is attenuated as 1/d.

kQ3AttenuationTypeInverseDistanceSquared
Intensity is attenuated as 1/(d*d).

TQ3FallOffType

typedef enum {
    kQ3FallOffTypeNone                          = 0,
    kQ3FallOffTypeLinear                        = 1,
    kQ3FallOffTypeExponential                   = 2,
    kQ3FallOffTypeCosine                        = 3,
    kQ3FallOffSize32                            = 0xFFFFFFFF
} TQ3FallOffType;

Discussion

Light fall-off methods.

The fall-off value of a light controls how the intensity of the light varies from the edge of the hot angle (where the light is at full intensity) to the outer angle (where the light intensity falls to zero).

Constants

kQ3FallOffTypeNone
Intensity does not fall off.

kQ3FallOffTypeLinear
Intensity falls off linearly.

kQ3FallOffTypeExponential
Intensity falls off exponentially.

kQ3FallOffTypeCosine
Intensity falls off as the cosine of the angle.