OpenCMISS-Zinc C++ API Documentation
Public Types | Public Member Functions | Protected Attributes | List of all members
OpenCMISS::Zinc::Light Class Reference

The light controls how vertices will be lit on a sceneviewer. More...

#include <light.hpp>

Public Types

enum  Type {
  TYPE_INVALID = CMZN_LIGHT_TYPE_INVALID, TYPE_AMBIENT = CMZN_LIGHT_TYPE_AMBIENT, TYPE_DIRECTIONAL = CMZN_LIGHT_TYPE_DIRECTIONAL, TYPE_POINT = CMZN_LIGHT_TYPE_POINT,
  TYPE_SPOT = CMZN_LIGHT_TYPE_SPOT
}
 

Public Member Functions

 Light (cmzn_light_id light_id)
 
 Light (const Light &light)
 
Lightoperator= (const Light &light)
 
bool isValid () const
 
cmzn_light_id getId () const
 
bool isManaged ()
 
int setManaged (bool value)
 
enum Type getType ()
 
int setType (enum Type type)
 
char * getName ()
 
int setName (const char *name)
 
double getConstantAttenuation ()
 
int setConstantAttenuation (double constantAttenuation)
 
double getLinearAttenuation ()
 
int setLinearAttenuation (double linearAttenuation)
 
double getQuadraticAttenuation ()
 
int setQuadraticAttenuation (double quadraticAttenuation)
 
int getColourRGB (double *valuesOut3)
 
int setColourRGB (const double *valuesIn3)
 
int getDirection (double *valuesOut3)
 
int setDirection (const double *valuesIn3)
 
int getPosition (double *valuesOut3)
 
int setPosition (const double *valuesIn3)
 
double getSpotCutoff ()
 
int setSpotCutoff (double cutoff)
 
double getSpotExponent ()
 
int setSpotExponent (double exponent)
 

Protected Attributes

cmzn_light_id id
 

Detailed Description

The light controls how vertices will be lit on a sceneviewer.

The light controls how vertices will be lit on a sceneviewer. Lighting and colouring of graphics are affected by the light colours, direction, position and type of lighting, in combination with material colours and other parameters.

Member Enumeration Documentation

The type of light. Various types imitate real-world light sources.

Enumerator
TYPE_INVALID 

Unspecified light type

TYPE_AMBIENT 

Ambient lighting from all directions. This multiplies the ambient colour of materials, giving a minimum colour where no other lights reach.

TYPE_DIRECTIONAL 

Directional light with parallel light rays from a source at infinity, hence also known as infinite light.

TYPE_POINT 

Positional light i.e. light radiating from a point. Takes into account attenuation parameters.

TYPE_SPOT 

Spot light taking position, direction, cut-off angle and attenuation into account when calculating the final colour.

Member Function Documentation

int OpenCMISS::Zinc::Light::getColourRGB ( double *  valuesOut3)
inline

Get the 3 component real vector giving the RGB colour of the light.

Parameters
valuesOut3Values of the colour will be output into this 3 component vector. It should be allocated with enough space for 3 components.
Returns
Status OpenCMISS::Zinc::OK on success, any other value on failure.
double OpenCMISS::Zinc::Light::getConstantAttenuation ( )
inline

Returns the value of the constant attenuation. Attenuation is the loss of light intensity over a distance. It only applies to spot and point lights.

attenuation factor: 1 / (c + k * l + k * q * q) where c, l, q and k is constant, linear, quadratic attenuation and distance respectively.

Returns
Value of the constant attenuation on success, 0 on failure.
int OpenCMISS::Zinc::Light::getDirection ( double *  valuesOut3)
inline

Get the 3 component vector giving the direction of the light. It only applies to infinite and spot lights.

Parameters
valuesOut3Values of the direction will be output into this 3 component vector. It should be allocated with enough space for 3 components.
Returns
Status OpenCMISS::Zinc::OK on success, any other value on failure.
cmzn_light_id OpenCMISS::Zinc::Light::getId ( ) const
inline

Return the C handle of the Light object.

Returns
C handle of Light if this objects is valid, 0 otherwise.
double OpenCMISS::Zinc::Light::getLinearAttenuation ( )
inline

Returns the value of the linear attenuation. Attenuation is the loss of light intensity over a distance. It only applies to spot and point lights.

attenuation factor: 1 / (c + k * l + k * q * q) where c, l, q and k is constant, linear, quadratic attenuation and distance respectively.

Returns
Value of the linear attenuation on success, 0 on failure.
char* OpenCMISS::Zinc::Light::getName ( )
inline

Return an allocated string containing light name.

Returns
allocated string containing light name, or NULL on failure. Up to caller to free using cmzn_deallocate().
int OpenCMISS::Zinc::Light::getPosition ( double *  valuesOut3)
inline

Get the 3 component vector giving the position of the light. It only applies to point and spot lights.

Parameters
valuesOut3Values of the position will be output into this 3 component vector. It should be allocated with enough space for 3 components.
Returns
Status OpenCMISS::Zinc::OK on success, any other value on failure.
double OpenCMISS::Zinc::Light::getQuadraticAttenuation ( )
inline

Returns the value of the quadratic attenuation. Attenuation is the loss of light intensity over a distance. It only applies to spot and point lights.

attenuation factor: 1 / (c + k * l + k * q * q) where c, l, q and k is constant, linear, quadratic attenuation and distance respectively.

Returns
Value of the quadratic attenuation on success, 0 on failure.
double OpenCMISS::Zinc::Light::getSpotCutoff ( )
inline

Gets the spotlight cutoff angle in degrees from 0 to 90. It only applies to spot light.

Returns
Value of the spot cutoff on success, 0 on failure.
double OpenCMISS::Zinc::Light::getSpotExponent ( )
inline

Gets the spotlight exponent which controls how concentrated the spotlight becomes as one approaches its axis. A value of 0.0 gives even illumination throughout the cutoff angle. It only applies to spot light.

Returns
Value of the spot exponent on success, 0 on failure.
enum Type OpenCMISS::Zinc::Light::getType ( )
inline

Gets the type of the light: AMBIENT, DIRECTIONAL, POINT or SPOT.

Returns
type of the light, otherwise CMZN_LIGHT_TYPE_INVALID.
bool OpenCMISS::Zinc::Light::isManaged ( )
inline

Get managed status of light in its owning light module.

See also
Light::setManaged
Returns
True if light is managed, otherwise false.
bool OpenCMISS::Zinc::Light::isValid ( ) const
inline

Check if this is a valid Light object.

Returns
Status True if object is valid, false otherwise.
int OpenCMISS::Zinc::Light::setColourRGB ( const double *  valuesIn3)
inline

Set the colour of the light using a 3 component vector of the RGB values. For ambient light type, the colour applies to ambient lighting calculations, blending with the ambient colour of materials. For all other light types, the colour applies to diffuse and specular lighting, blending with materials' diffuse and specular colours.

Parameters
valuesIn3Values of the colour to be set, it must be a 3 component vector storing the RGB value. Colour values range from 0.0 to 1.0 (max).
Returns
Status OpenCMISS::Zinc::OK on success, any other value on failure.
int OpenCMISS::Zinc::Light::setConstantAttenuation ( double  constantAttenuation)
inline

Set the value of the constant attenuation. Attenuation is the loss of light intensity over a distance. It only applies to spot and point lights.

attenuation factor: 1 / (c + k * l + k * q * q) where c, l, q and k is constant, linear, quadratic attenuation and distance respectively.

Parameters
constantAttenuationNon-negative float representing the value of constant attenuation to be set.
Returns
Status OpenCMISS::Zinc::OK on success, otherwise OpenCMISS::Zinc::ERROR_ARGUMENT.
int OpenCMISS::Zinc::Light::setDirection ( const double *  valuesIn3)
inline

Set the direction of the light using a 3 component vector. It only applies to infinite and spot lights.

Parameters
valuesIn3Values of the direction to set, must be a 3 component vector storing the direction value.
Returns
Status OpenCMISS::Zinc::OK on success, any other value on failure.
int OpenCMISS::Zinc::Light::setLinearAttenuation ( double  linearAttenuation)
inline

Set the value of the linear attenuation. Attenuation is the loss of light intensity over a distance. It only applies to spot and point lights.

attenuation factor: 1 / (c + k * l + k * q * q) where c, l, q and k is constant, linear, quadratic attenuation and distance respectively.

Parameters
linearAttenuationnon-negative float representing the value of linear attenuation to be set.
Returns
Status OpenCMISS::Zinc::OK on success, otherwise OpenCMISS::Zinc::ERROR_ARGUMENT.
int OpenCMISS::Zinc::Light::setManaged ( bool  value)
inline

Set managed status of light in its owning light module. If true (managed) the light will remain indefinitely in the light module even if no external references are held. If false (unmanaged) the light will be automatically removed from the module when no longer referenced externally, effectively marking it as pending destruction. All new objects are unmanaged unless stated otherwise.

Parameters
valueThe new value for the managed flag: true or false.
Returns
Status OpenCMISS::Zinc::OK on success, otherwise OpenCMISS::Zinc::ERROR_ARGUMENT.
int OpenCMISS::Zinc::Light::setName ( const char *  name)
inline

Set/change name for light. Must be unique in the light module.

Parameters
namename to be set to the light
Returns
status OpenCMISS::Zinc::OK if successfully set/change name for light, any other value on failure.
int OpenCMISS::Zinc::Light::setPosition ( const double *  valuesIn3)
inline

Set the position of the light using a 3 component vector. It only applies to point and spot lights.

Parameters
valuesIn3Values of the position to set, must be a 3 component vector storing the position value.
Returns
Status OpenCMISS::Zinc::OK on success, any other value on failure.
int OpenCMISS::Zinc::Light::setQuadraticAttenuation ( double  quadraticAttenuation)
inline

Set the value of the quadratic attenuation. Attenuation is the loss of light intensity over a distance. It only applies to spot and point lights.

attenuation factor: 1 / (c + k * l + k * q * q) where c, l, q and k is constant, linear, quadratic attenuation and distance respectively.

Parameters
quadraticAttenuationNon-negative float representing the value of quadratic attenuation to be set.
Returns
Status OpenCMISS::Zinc::OK on success, otherwise OpenCMISS::Zinc::ERROR_ARGUMENT.
int OpenCMISS::Zinc::Light::setSpotCutoff ( double  cutoff)
inline

Sets the spotlight cutoff angle in degrees from 0 to 90. It only applies to spot light.

Parameters
cutoffNew value to set, the value must be between 0.0 and 90.0.
Returns
Status OpenCMISS::Zinc::OK on success, any other value on failure.
int OpenCMISS::Zinc::Light::setSpotExponent ( double  exponent)
inline

Sets the spotlight exponent which controls how concentrated the spotlight becomes as one approaches its axis. A value of 0.0 gives even illumination throughout the cutoff angle. It only applies to spot light.

Parameters
exponentNew spot exponent value to be set for light.
Returns
Status OpenCMISS::Zinc::OK on success, any other value on failure.
int OpenCMISS::Zinc::Light::setType ( enum Type  type)
inline

Sets the type of the light: AMBIENT, DIRECTIONAL, POINT or SPOT.

Returns
Status OpenCMISS::Zinc::OK on success, otherwise OpenCMISS::Zinc::ERROR_ARGUMENT.

The documentation for this class was generated from the following file: