#include "beastapitypes.h"

File Description

The api for specifying light sources in beast.

Typedefs
typedef uint32	ILBLightStatsMask

Enumerations
enum	ILBFalloffType { ILB_FO_EXPONENT = 0, ILB_FO_MAX_RANGE, ILB_FO_POLYNOMIAL }

enum	ILBLightStatOperation { ILB_LSOP_DISABLE, ILB_LSOP_ENABLE, ILB_LSOP_SET }

enum	ILBLightStats { ILB_LS_VISIBLE_FOR_EYE = 0x00000001, ILB_LS_VISIBLE_FOR_REFLECTIONS = 0x00000002, ILB_LS_VISIBLE_FOR_REFRACTIONS = 0x00000004, ILB_LS_VISIBLE_FOR_GI = 0x00000008 }

enum	ILBLightType { ILB_LST_DIRECTIONAL = 0, ILB_LST_POINT, ILB_LST_AREA, ILB_LST_SPOT, ILB_LST_WINDOW, ILB_LST_SKY, ILB_LST_AMBIENT }

enum	ILBLightVolumeType { ILB_LVT_INFINITY = 0, ILB_LVT_SPHERE, ILB_LVT_CUBE }

Functions
ILBStatus	ILBAddLightLightLinks (ILBLightHandle light, ILBLightLinkMode mode, const ILBInstanceHandle *instances, int32 count)

ILBStatus	ILBChangeLightType (ILBLightHandle light, ILBLightType newType, ILBLightHandle *newHandle)

ILBStatus	ILBCreateAmbientLight (ILBSceneHandle scene, ILBConstString name, const ILBMatrix4x4 transform, const ILBLinearRGB intensity, ILBLightHandle *light)

ILBStatus	ILBCreateAreaLight (ILBSceneHandle scene, ILBConstString name, const ILBMatrix4x4 transform, const ILBLinearRGB intensity, ILBLightHandle *light)

ILBStatus	ILBCreateDirectionalLight (ILBSceneHandle scene, ILBConstString name, const ILBMatrix4x4 transform, const ILBLinearRGB intensity, ILBLightHandle *light)

ILBStatus	ILBCreatePointLight (ILBSceneHandle scene, ILBConstString name, const ILBMatrix4x4 transform, const ILBLinearRGB intensity, ILBLightHandle *light)

ILBStatus	ILBCreateSkyLight (ILBSceneHandle scene, ILBConstString name, const ILBMatrix4x4 transform, const ILBLinearRGB intensity, ILBLightHandle *light)

ILBStatus	ILBCreateSpotLight (ILBSceneHandle scene, ILBConstString name, const ILBMatrix4x4 transform, const ILBLinearRGB intensity, ILBLightHandle *light)

ILBStatus	ILBCreateWindowLight (ILBSceneHandle scene, ILBConstString name, const ILBMatrix4x4 transform, const ILBLinearRGB intensity, ILBLightHandle *light)

ILBStatus	ILBDeleteLightSource (ILBLightHandle light)

ILBStatus	ILBGetClippingPlanes (ILBLightHandle light, float nearDistance, float farDistance)

ILBStatus	ILBGetLightCastShadows (ILBLightHandle light, ILBBool *castShadows)

ILBStatus	ILBGetLightColor (ILBLightHandle light, ILBLinearRGB *color)

ILBStatus	ILBGetLightDisplayName (ILBLightHandle light, ILBStringHandle *displayName)

ILBStatus	ILBGetLightExponentFalloff (ILBLightHandle light, float cutoff, float exponent, ILBBool *clamp)

ILBStatus	ILBGetLightFalloffType (ILBLightHandle light, ILBFalloffType *type)

ILBStatus	ILBGetLightIntensity (ILBLightHandle light, float *intensity)

ILBStatus	ILBGetLightIntensityScale (ILBLightHandle light, float directScale, float indirectScale)

ILBStatus	ILBGetLightMaxRangeFalloff (ILBLightHandle light, float cutoff, float exponent)

ILBStatus	ILBGetLightName (ILBLightHandle light, ILBStringHandle *name)

ILBStatus	ILBGetLightPolynomialFalloff (ILBLightHandle light, float cutoff, float constant, float linear, float quadratic, ILBBool *clamp)

ILBStatus	ILBGetLightShadowSamples (ILBLightHandle light, int32 *shadowSamples)

ILBStatus	ILBGetLightStats (ILBLightHandle light, ILBLightStatsMask stats, ILBLightStatsMask *result)

ILBStatus	ILBGetLightTransform (ILBLightHandle light, ILBMatrix4x4 *transform)

ILBStatus	ILBGetLightType (ILBLightHandle light, ILBLightType *type)

ILBStatus	ILBGetLightVolumeType (ILBLightHandle light, ILBLightVolumeType *type)

ILBStatus	ILBGetShadowAngle (ILBLightHandle light, float *angleRadians)

ILBStatus	ILBGetShadowRadius (ILBLightHandle light, float *radius)

ILBStatus	ILBGetSkyLightTexture (ILBLightHandle light, ILBTextureHandle *texture)

ILBStatus	ILBGetSkyLightTextureFilter (ILBLightHandle light, float *filter)

ILBStatus	ILBGetSkyLightVolumeType (ILBLightHandle light, ILBLightVolumeType *type)

ILBStatus	ILBGetSpotlightCone (ILBLightHandle light, float angleRadians, float penumbraAngleRadians, float *penumbraExponent)

ILBStatus	ILBSetCastShadows (ILBLightHandle light, ILBBool castShadows)

ILBStatus	ILBSetClippingPlanes (ILBLightHandle light, float nearDistance, float farDistance)

ILBStatus	ILBSetFalloff (ILBLightHandle light, ILBFalloffType type, float exponent, float cutoff, ILBBool clampToOne)

ILBStatus	ILBSetIntensityScale (ILBLightHandle light, float directScale, float indirectScale)

ILBStatus	ILBSetLightColor (ILBLightHandle light, const ILBLinearRGB *color)

ILBStatus	ILBSetLightDisplayName (ILBLightHandle light, ILBConstString displayName)

ILBStatus	ILBSetLightExponentFalloff (ILBLightHandle light, float cutoff, float exponent, ILBBool clampToOne)

ILBStatus	ILBSetLightIntensity (ILBLightHandle light, float intensity)

ILBStatus	ILBSetLightMaxRangeFalloff (ILBLightHandle light, float cutoff, float exponent)

ILBStatus	ILBSetLightPolynomialFalloff (ILBLightHandle light, float cutoff, float constant, float linear, float quadratic, ILBBool clampToOne)

ILBStatus	ILBSetLightProjectedTexture (ILBLightHandle light, ILBTextureHandle texture)

ILBStatus	ILBSetLightRampEntry (ILBLightHandle light, float position, const ILBLinearRGB *value)

ILBStatus	ILBSetLightStats (ILBLightHandle light, ILBLightStatsMask stats, ILBLightStatOperation operation)

ILBStatus	ILBSetLightTransform (ILBLightHandle light, const ILBMatrix4x4 *transform)

ILBStatus	ILBSetLightVolumeType (ILBLightHandle light, ILBLightVolumeType type)

ILBStatus	ILBSetShadowAngle (ILBLightHandle light, float angleRadians)

ILBStatus	ILBSetShadowRadius (ILBLightHandle light, float radius)

ILBStatus	ILBSetShadowSamples (ILBLightHandle light, int32 samples)

ILBStatus	ILBSetSkyLightTexture (ILBLightHandle light, ILBTextureHandle texture)

ILBStatus	ILBSetSkyLightTextureFilter (ILBLightHandle light, float filter)

ILBStatus	ILBSetSkyLightVolumeType (ILBLightHandle light, ILBLightVolumeType type)

ILBStatus	ILBSetSpotlightCone (ILBLightHandle light, float angleRadians, float penumbraAngleRadians, float penumbraExponent)

Typedef Documentation

typedef uint32 ILBLightStatsMask

Type representing multiple light stats.

Combine light stats using the or operator (|).
Example:
ILBLightStatsMask lsMask = ILB_LS_VISIBLE_FOR_EYE | ILB_LS_VISIBLE_FOR_GI;

Enumeration Type Documentation

enum ILBFalloffType

Describes different falloff for light sources.

Enumerator

ILB_FO_EXPONENT

Computes falloff as (1.0f / distance) ^ exponent
Note that an exponent of 0 gives no falloff.

ILB_FO_MAX_RANGE

Computes falloff as (max((maxRange - distance), 0) / maxRange) ^ exponent
.

ILB_FO_POLYNOMIAL

OpenGL-type fall off.

Not supported yet.

enum ILBLightStatOperation

Selects if the light stats should be enabled or disabled.

Enumerator
ILB_LSOP_DISABLE	Sets the light stats supplied to false.
ILB_LSOP_ENABLE	Sets the light stats supplied to true.
ILB_LSOP_SET	Sets the light stats to the value of the light mask.

enum ILBLightStats

Status bit masks for light sources.

Enumerator
ILB_LS_VISIBLE_FOR_EYE	Controls if the light source should be visible for camera rays.
ILB_LS_VISIBLE_FOR_REFLECTIONS	Controls if the light source should be visible for reflection rays.
ILB_LS_VISIBLE_FOR_REFRACTIONS	Controls if the light source should be visible for refraction rays.
ILB_LS_VISIBLE_FOR_GI	Controls if the light source should be visible for global illumination rays.

enum ILBLightType

Describes light types.

Enumerator
ILB_LST_DIRECTIONAL	Directional light.
ILB_LST_POINT	Point light.
ILB_LST_AREA	Area light.
ILB_LST_SPOT	Spot light.
ILB_LST_WINDOW	Window light.
ILB_LST_SKY	Sky light.
ILB_LST_AMBIENT	Ambient light.

enum ILBLightVolumeType

Describes different light volumes for light sources.

Enumerator
ILB_LVT_INFINITY	Specified the whole 3D space.
ILB_LVT_SPHERE	A sphere volume.
ILB_LVT_CUBE	A cube volume.

Function Documentation

ILBStatus ILBAddLightLightLinks	(	ILBLightHandle	light,
		ILBLightLinkMode	mode,
		const ILBInstanceHandle *	instances,
		int32	count
	)

Adds a light centric light link list.

Parameters

light	the light source to add light links to
mode	sets whether to link or unlink the light to the instances
instances	an array of instances to link to the light
count	the number of instances present in the instances array

Returns: The result of the operation.

ILBStatus ILBChangeLightType	(	ILBLightHandle	light,
		ILBLightType	newType,
		ILBLightHandle *	newHandle
	)

Changes the type of a light source.

Retains basic parameters like transform and color but all light type specific parameters are reset to default.

Parameters

light	the light to change type
newType
newHandle

Returns: The result of the operation.

ILBStatus ILBCreateAmbientLight	(	ILBSceneHandle	scene,
		ILBConstString	name,
		const ILBMatrix4x4 *	transform,
		const ILBLinearRGB *	intensity,
		ILBLightHandle *	light
	)

Add an ambient light to the scene.

It illuminates the whole scene by default, but this can be altered by setting a light volume type to the light. Use the light transform matrix to change the position and size of the light volume.

Parameters

scene	the scene the ambient light should be a part of
name	the name of the ambient light, must be unique within the scene.
transform	the object space to world space transform for the light
intensity	the colored intensity of the light source
light	the handle to store the generated light source in

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp, and examples/code/lightsources/lightsources.cpp.

ILBStatus ILBCreateAreaLight	(	ILBSceneHandle	scene,
		ILBConstString	name,
		const ILBMatrix4x4 *	transform,
		const ILBLinearRGB *	intensity,
		ILBLightHandle *	light
	)

Add an area light to the scene It points in negative Y direction by default, use the matrix to change its direction.

The area light extends -1.0 to 1.0 in the X/Z dimensions, use scaling to control its area

Parameters

scene	the scene the light should be a part of
name	the name of the light, must be unique within the scene.
transform	the object space to world space transform for the light. It controls the area of the light as well.
intensity	the colored intensity of the light source
light	the handle to store the generated light source in

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp, examples/code/lightsources/lightsources.cpp, examples/code/liveernst/liveernst.cpp, examples/code/lua/lua.cpp, examples/code/pointcloud/pointcloud.cpp, and examples/code/rnm/rnm.cpp.

ILBStatus ILBCreateDirectionalLight	(	ILBSceneHandle	scene,
		ILBConstString	name,
		const ILBMatrix4x4 *	transform,
		const ILBLinearRGB *	intensity,
		ILBLightHandle *	light
	)

Add a directional light to the scene It points in negative Y direction by default, use the matrix to change its direction.

Parameters

scene	the scene the directional light should be a part of
name	the name of the directional light, must be unique within the scene.
transform	the object space to world space transform for the light.
intensity	the colored intensity of the light source
light	the handle to store the generated light source in

Returns: The result of the operation.

Examples:: examples-physical/code/common/samplescommon.h, examples/code/atlas/atlas.cpp, examples/code/baking/baking.cpp, examples/code/cache/cache.cpp, examples/code/ernst/ernst.cpp, examples/code/lightsources/lightsources.cpp, examples/code/liveernst/liveernst.cpp, examples/code/materials/materials.cpp, examples/code/occlusion/occlusion.cpp, examples/code/readback/readback.cpp, examples/code/renderstats/renderstats.cpp, and examples/code/simple/simple.cpp.

ILBStatus ILBCreatePointLight	(	ILBSceneHandle	scene,
		ILBConstString	name,
		const ILBMatrix4x4 *	transform,
		const ILBLinearRGB *	intensity,
		ILBLightHandle *	light
	)

Add a point light to the scene.

Parameters

scene	the scene the point light should be a part of
name	the name of the point light, must be unique within the scene.
transform	the object space to world space transform for the light
intensity	the colored intensity of the light source
light	the handle to store the generated light source in

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp, examples/code/lightsources/lightsources.cpp, examples/code/liveernst/liveernst.cpp, and examples/code/shbaking/shbaking.cpp.

ILBStatus ILBCreateSkyLight	(	ILBSceneHandle	scene,
		ILBConstString	name,
		const ILBMatrix4x4 *	transform,
		const ILBLinearRGB *	intensity,
		ILBLightHandle *	light
	)

Add a sky light to the scene It illuminates the whole scene by default, but this can be altered by setting a light volume type to the sky light.

Use the light transform matrix to change the position and size of the light volume.

Parameters

scene	the scene the light should be a part of
name	the name of the light, must be unique within the scene.
transform	the object space to world space transform for the light. It controls the light volume of the light as well
intensity	the colored intensity of the light source
light	the handle to store the generated light source in

Returns: The result of the operation.

Examples:: examples-physical/code/common/samplescommon.h, examples/code/atlas/atlas.cpp, examples/code/baking/baking.cpp, examples/code/cache/cache.cpp, examples/code/ernst/ernst.cpp, examples/code/lightsources/lightsources.cpp, examples/code/liveernst/liveernst.cpp, examples/code/materials/materials.cpp, examples/code/readback/readback.cpp, examples/code/renderstats/renderstats.cpp, and examples/code/simple/simple.cpp.

ILBStatus ILBCreateSpotLight	(	ILBSceneHandle	scene,
		ILBConstString	name,
		const ILBMatrix4x4 *	transform,
		const ILBLinearRGB *	intensity,
		ILBLightHandle *	light
	)

Add a spot light to the scene.

It points in the negative Y-direction by default, use the matrix to point it in a different direction. The default cone angle is 90 degrees.

Parameters

scene	the scene the light should be a part of
name	the name of the light, must be unique within the scene.
transform	the object space to world space transform for the light.
intensity	the colored intensity of the light source
light	the handle to store the generated light source in

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp, examples/code/lightsources/lightsources.cpp, examples/code/liveernst/liveernst.cpp, and examples/code/uvset/uvset.cpp.

ILBStatus ILBCreateWindowLight	(	ILBSceneHandle	scene,
		ILBConstString	name,
		const ILBMatrix4x4 *	transform,
		const ILBLinearRGB *	intensity,
		ILBLightHandle *	light
	)

Add a window light to the scene It points in negative Y direction by default, use the matrix to change its direction.

The window light extends -1.0 to 1.0 in the X/Z dimensions, use scaling to control its area

Parameters

scene	the scene the light should be a part of
name	the name of the light, must be unique within the scene.
transform	the object space to world space transform for the light. It controls the area of the light as well
intensity	the colored intensity of the light source
light	the handle to store the generated light source in

Returns: The result of the operation.

Examples:: examples/code/lightsources/lightsources.cpp.

ILBStatus ILBDeleteLightSource ( ILBLightHandle light )

Deletes a light source from a scene.

Only possible for dynamic scenes, ie. scenes associated with a live ernst job.

Parameters

light light to delete

Returns: The result of the operation.

ILBStatus ILBGetClippingPlanes	(	ILBLightHandle	light,
		float *	nearDistance,
		float *	farDistance
	)

Gets distance to spotlight clipping planes.

Both light shading and shadow casting is clipped by these planes but attenuation is still calculated from light source position.
Only works for spot lights.

Parameters

light	the light source to get clipping distances for
nearDistance	the distance to near clipping plane
farDistance	the distance to far clipping plane

Returns: The result of the operation.

ILBStatus ILBGetLightCastShadows	(	ILBLightHandle	light,
		ILBBool *	castShadows
	)

Returns whether a light source cast shadows.

This is used for lights returned from an Ernst session.

Parameters

light	the light to check shadow status
castShadows	is set to true if light source cast shadows, false otherwise

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp.

ILBStatus ILBGetLightColor	(	ILBLightHandle	light,
		ILBLinearRGB *	color
	)

Gets the color of a light source.

This is used for lights returned from an Ernst session.

Parameters

light	the light to get the color for
color	the returned light color

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp.

ILBStatus ILBGetLightDisplayName	(	ILBLightHandle	light,
		ILBStringHandle *	displayName
	)

Gets the display name of a light source.

Display names are not unique within the scene and should only be used by tools to give human understandable names to objects This is used for lights returned from an Ernst session.

Parameters

light	the light to get the name for
displayName	the returned light display name

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp.

ILBStatus ILBGetLightExponentFalloff	(	ILBLightHandle	light,
		float *	cutoff,
		float *	exponent,
		ILBBool *	clamp
	)

Returns the falloff parameters from a light source with Exponent falloff.

This is used for lights returned from an Ernst session.

Parameters

light	the light to get shadow samples
cutoff	the falloff cutoff
exponent	the falloff exponent
clamp	sets whether to clamp the falloff to be lower or equal to one. If set to false, the falloff is allowed to scale the intensity of the light up as well as down.

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp.

ILBStatus ILBGetLightFalloffType	(	ILBLightHandle	light,
		ILBFalloffType *	type
	)

Returns the falloff type from a light source.

This is used for lights returned from an Ernst session.

Parameters

light	the light to get shadow samples
type	the returned falloff type

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp.

ILBStatus ILBGetLightIntensity	(	ILBLightHandle	light,
		float *	intensity
	)

Gets light intensity for a light source.

This is used for lights returned from an Ernst session.

Parameters

light	the light source to get intensity from
intensity	the light intensity

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp.

ILBStatus ILBGetLightIntensityScale	(	ILBLightHandle	light,
		float *	directScale,
		float *	indirectScale
	)

Gets scale for direct and indirect light intensity for a light source.

This is used for lights returned from an Ernst session.

Parameters

light	the light source to get intensities
directScale	direct light intensity scale
indirectScale	indirect light intensity scale

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp.

ILBStatus ILBGetLightMaxRangeFalloff	(	ILBLightHandle	light,
		float *	cutoff,
		float *	exponent
	)

Returns the falloff parameters from a light source with MaxRange falloff.

This is used for lights returned from an Ernst session.

Parameters

light	the light to get shadow samples
cutoff	the falloff cutoff
exponent	the falloff exponent

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp.

ILBStatus ILBGetLightName	(	ILBLightHandle	light,
		ILBStringHandle *	name
	)

Gets the name of a light source.

This is used for lights returned from an Ernst session.

Parameters

light	the light to get the name for
name	the returned light name

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp.

ILBStatus ILBGetLightPolynomialFalloff	(	ILBLightHandle	light,
		float *	cutoff,
		float *	constant,
		float *	linear,
		float *	quadratic,
		ILBBool *	clamp
	)

Returns the falloff parameters from a light source with Polynomial falloff.

This is used for lights returned from an Ernst session.

Parameters

light	the light to get shadow samples
cutoff	the falloff cutoff
constant	the falloff constant factor
linear	the falloff linear factor
quadratic	the falloff quadratic factor
clamp	sets whether to clamp the falloff to be lower or equal to one. If set to false, the falloff is allowed to scale the intensity of the light up as well as down.

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp.

ILBStatus ILBGetLightShadowSamples	(	ILBLightHandle	light,
		int32 *	shadowSamples
	)

Returns the number of shadow samples a light source will use.

This is used for lights returned from an Ernst session.

Parameters

light	the light to get shadow samples
shadowSamples	the number of shadow samples

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp.

ILBStatus ILBGetLightStats	(	ILBLightHandle	light,
		ILBLightStatsMask	stats,
		ILBLightStatsMask *	result
	)

Query light stats for a light source.

Parameters

light	the light source to get light stats from.
stats	the stats to query. Can be multiple light stats or:ed together.
result	the result of the query. A bitwise AND operation is done on the individual stats. given stats are true the result is true, and false otherwise.

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp.

ILBStatus ILBGetLightTransform	(	ILBLightHandle	light,
		ILBMatrix4x4 *	transform
	)

Gets the transform of a light source.

This is used for lights returned from an Ernst session.

Parameters

light	the light to get the transform for
transform	the returned light transform

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp.

ILBStatus ILBGetLightType	(	ILBLightHandle	light,
		ILBLightType *	type
	)

Gets the type of a light source.

This is used for lights returned from an Ernst session.

Parameters

light	the light to get the type for
type	the returned light type

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp.

ILBStatus ILBGetLightVolumeType	(	ILBLightHandle	light,
		ILBLightVolumeType *	type
	)

Gets light volume type for a light source.

Only valid for ambient lights and sky lights. This is used for lights returned from an Ernst session.

Parameters

light	light to set light volume type on
type	the volume type to use

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp.

ILBStatus ILBGetShadowAngle	(	ILBLightHandle	light,
		float *	angleRadians
	)

Gets the angle covered of the sky for a directional light or window light for shadow casting purposes.

This is used for lights returned from an Ernst session.

Parameters

light	the light source to get the radius on.
angleRadians	the angle in radians.

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp.

ILBStatus ILBGetShadowRadius	(	ILBLightHandle	light,
		float *	radius
	)

Gets a radius for the light source as a shadow caster.

Only valid for point and spot lights. This is used for lights returned from an Ernst session.

Parameters

light	the light source to get the radius on.
radius	the radius.

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp.

ILBStatus ILBGetSkyLightTexture	(	ILBLightHandle	light,
		ILBTextureHandle *	texture
	)

Gets a texture from a sky light.

Only valid for sky lights This is used for lights returned from an Ernst session.

Parameters

light	light to get texture from
texture	the texture handle

Returns: The result of the operation.

ILBStatus ILBGetSkyLightTextureFilter	(	ILBLightHandle	light,
		float *	filter
	)

Gets texture filter size from a sky light.

Only valid for sky lights This is used for lights returned from an Ernst session.

Parameters

light	light to get filter size from
filter	the filter size

Returns: The result of the operation.

ILBStatus ILBGetSkyLightVolumeType	(	ILBLightHandle	light,
		ILBLightVolumeType *	type
	)

Gets light volume type for a sky light.

Only valid for sky lights This is used for lights returned from an Ernst session.

Deprecated:

Use ILBGetLightVolumeType() instead

Parameters

light	light to set light volume type on
type	the volume type to use

Returns: The result of the operation.

ILBStatus ILBGetSpotlightCone	(	ILBLightHandle	light,
		float *	angleRadians,
		float *	penumbraAngleRadians,
		float *	penumbraExponent
	)

Gets the cone angle for a spotlight.

The cone is given in radians for the entire cone (as opposed to the angle towards the forward direction). The penumbra angle is the angle from the edge of the cone over which the intensity falls off to zero. The effective spread of the cone is max( angleRadians, angleRadians + 2*penumbraAngleRadians ) since the penumbra angle can be both positive and negative. This is used for lights returned from an Ernst session.

Parameters

light	the light source to get cone angle for
angleRadians	the angle in radians for the cone
penumbraAngleRadians	the angle of the penumbra of the spot light. It's given as the difference from the cone angle and can be both negative and positive.
penumbraExponent	the exponent for the gradient in the penumbra

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp.

ILBStatus ILBSetCastShadows	(	ILBLightHandle	light,
		ILBBool	castShadows
	)

Flags whether the light cast shadows or not.

Enabled by default

Parameters

light	the light source in question.
castShadows	sets if shadow casting should be enabled or not

Returns: The result of the operation.

Examples:: examples/code/atlas/atlas.cpp, examples/code/baking/baking.cpp, examples/code/cache/cache.cpp, examples/code/ernst/ernst.cpp, examples/code/lightsources/lightsources.cpp, examples/code/liveernst/liveernst.cpp, examples/code/lua/lua.cpp, examples/code/materials/materials.cpp, examples/code/occlusion/occlusion.cpp, examples/code/pointcloud/pointcloud.cpp, examples/code/readback/readback.cpp, examples/code/renderstats/renderstats.cpp, examples/code/rnm/rnm.cpp, examples/code/shbaking/shbaking.cpp, and examples/code/simple/simple.cpp.

ILBStatus ILBSetClippingPlanes	(	ILBLightHandle	light,
		float	nearDistance,
		float	farDistance
	)

Sets distance to spotlight clipping planes.

Both light shading and shadow casting is clipped by these planes but attenuation is still calculated from light source position.
Only works for spot lights.

Parameters

light	the light source to set clipping distances for
nearDistance	the distance to near clipping plane
farDistance	the distance to far clipping plane

Returns: The result of the operation.

ILBStatus ILBSetFalloff	(	ILBLightHandle	light,
		ILBFalloffType	type,
		float	exponent,
		float	cutoff,
		ILBBool	clampToOne
	)

Sets the falloff for a light source.

Not valid for directional lights, sky lights and ambient lights. By default falloff is disabled. By default clamping is enabled.

Parameters

light	the light source to set falloff for
type	the falloff type to use
exponent	sets the exponent for the falloff
cutoff	sets the influence range for the light source. It affects both falloff types, for exponent it's a hard cutoff where the light stops affecting at all. For max range it sets where the light intensity fades to zero
clampToOne	sets whether to clamp the falloff to be lower or equal to one. If set to false, the falloff is allowed to scale the intensity of the light up as well as down.

Returns: The result of the operation.

Examples:: examples/code/lightsources/lightsources.cpp.

ILBStatus ILBSetIntensityScale	(	ILBLightHandle	light,
		float	directScale,
		float	indirectScale
	)

Sets scale for direct and indirect light intensity for a light source.

Parameters

light	the light source to set intensities
directScale	direct light intensity scale
indirectScale	indirect light intensity scale

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp, and examples/code/liveernst/liveernst.cpp.

ILBStatus ILBSetLightColor	(	ILBLightHandle	light,
		const ILBLinearRGB *	color
	)

Sets the color for a light source.

Parameters

light	the light source to change
color	the new color

Returns: The result of the operation.

ILBStatus ILBSetLightDisplayName	(	ILBLightHandle	light,
		ILBConstString	displayName
	)

Sets the display name for the light source.

This name does not have to be unique within the scene and can be used by tools to give human understandable names to objects that has names that are generated and for some reason isn't suitable to read

Parameters

light	the light to set the name for
displayName	the display name to set

Examples:: examples/code/ernst/ernst.cpp, and examples/code/liveernst/liveernst.cpp.

ILBStatus ILBSetLightExponentFalloff	(	ILBLightHandle	light,
		float	cutoff,
		float	exponent,
		ILBBool	clampToOne
	)

Sets the falloff to type "Exponent" for a light source.

Not valid for directional lights, sky lights and ambient lights. By default falloff is disabled. By default clamping is enabled.

Parameters

light	the light source to set falloff for
cutoff	hard cutoff range where the light stops affecting at all.
exponent	sets the exponent for the falloff
clampToOne	sets whether to clamp the falloff to be lower or equal to one. If set to false, the falloff is allowed to scale the intensity of the light up as well as down.

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp, and examples/code/liveernst/liveernst.cpp.

ILBStatus ILBSetLightIntensity	(	ILBLightHandle	light,
		float	intensity
	)

Sets light intensity for a light source.

Parameters

light	the light source to set intensity
intensity	the light intensity

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp, and examples/code/liveernst/liveernst.cpp.

ILBStatus ILBSetLightMaxRangeFalloff	(	ILBLightHandle	light,
		float	cutoff,
		float	exponent
	)

Sets the falloff to type "Max Range" for a light source.

Not valid for directional lights, sky lights and ambient lights. By default falloff is disabled. By default clamping is enabled.

Parameters

light	the light source to set falloff for
cutoff	sets where the light intensity reaches zero.
exponent	sets the exponent for the falloff

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp, and examples/code/liveernst/liveernst.cpp.

ILBStatus ILBSetLightPolynomialFalloff	(	ILBLightHandle	light,
		float	cutoff,
		float	constant,
		float	linear,
		float	quadratic,
		ILBBool	clampToOne
	)

Sets the falloff to type "Polynomial" for a light source.

Not valid for directional lights, sky lights and ambient lights. By default falloff is disabled. By default clamping is enabled.

Parameters

light	the light source to set falloff for
cutoff	sets the influence range for the light source.
constant
linear
quadratic
clampToOne	sets whether to clamp the falloff to be lower or equal to one. If set to false, the falloff is allowed to scale the intensity of the light up as well as down.

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp, and examples/code/liveernst/liveernst.cpp.

ILBStatus ILBSetLightProjectedTexture	(	ILBLightHandle	light,
		ILBTextureHandle	texture
	)

Sets a projected texture for a light source (gobo).

Only works for spot lights.

Parameters

light	light to add gobo on
texture	texture to use as gobo

Returns: The result of the operation.

Examples:: examples/code/lightsources/lightsources.cpp.

ILBStatus ILBSetLightRampEntry	(	ILBLightHandle	light,
		float	position,
		const ILBLinearRGB *	value
	)

Adds a light ramp entry for falloff calculation.

The ramp extends from 0 to 1 in light space, use the transformation matrix to control the scale.
Works on point and spot lights.

Parameters

light	light source to manipulate
position	position in the ramp. Must be greater than 0 and greater than the last position.
value	color of the given position in the ramp.

Returns: The result of the operation.

Examples:: examples/code/lightsources/lightsources.cpp.

ILBStatus ILBSetLightStats	(	ILBLightHandle	light,
		ILBLightStatsMask	stats,
		ILBLightStatOperation	operation
	)

Sets light status bits for a light source.

Parameters

light	the light source to set light stats for
stats	the stats to modify. Can be multiple light stats or:ed together
operation	selects whether to enable or disable the selected light stats.

Returns: The result of the operation.

Examples:: examples/code/atlas/atlas.cpp, examples/code/baking/baking.cpp, examples/code/ernst/ernst.cpp, and examples/code/liveernst/liveernst.cpp.

ILBStatus ILBSetLightTransform	(	ILBLightHandle	light,
		const ILBMatrix4x4 *	transform
	)

Sets the transform for a light source.

Parameters

light	the light source to change
transform	the new transform

Returns: The result of the operation.

Examples:: examples/code/liveernst/liveernst.cpp.

ILBStatus ILBSetLightVolumeType	(	ILBLightHandle	light,
		ILBLightVolumeType	type
	)

Sets light volume type for a light source.

Only works for ambient lights and sky lights.

Parameters

light	light to set light volume type on
type	the volume type to use

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp, and examples/code/lightsources/lightsources.cpp.

ILBStatus ILBSetShadowAngle	(	ILBLightHandle	light,
		float	angleRadians
	)

Sets the angle covered of the sky for a directional light or window light for shadow casting purposes.

The angle is 0 by default

Parameters

light	the light source to set the radius on.
angleRadians	the angle in radians.

Returns: The result of the operation.

Examples:: examples-physical/code/common/samplescommon.h, examples/code/atlas/atlas.cpp, examples/code/baking/baking.cpp, examples/code/cache/cache.cpp, examples/code/ernst/ernst.cpp, examples/code/lightsources/lightsources.cpp, examples/code/liveernst/liveernst.cpp, examples/code/materials/materials.cpp, examples/code/occlusion/occlusion.cpp, examples/code/readback/readback.cpp, examples/code/renderstats/renderstats.cpp, and examples/code/simple/simple.cpp.

ILBStatus ILBSetShadowRadius	(	ILBLightHandle	light,
		float	radius
	)

Sets a radius for the light source as a shadow caster.

Only valid for point and spot lights. The radius is 0 by default.

Parameters

light	the light source to set the radius on.
radius	the radius.

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp, examples/code/lightsources/lightsources.cpp, and examples/code/liveernst/liveernst.cpp.

ILBStatus ILBSetShadowSamples	(	ILBLightHandle	light,
		int32	samples
	)

Sets the maximum number of shadow samples for the light source.

Set to 1 by default

Parameters

light	the light source to set the radius on.
samples	the number of samples.

Returns: The result of the operation.

Examples:: examples/code/atlas/atlas.cpp, examples/code/baking/baking.cpp, examples/code/cache/cache.cpp, examples/code/ernst/ernst.cpp, examples/code/lightsources/lightsources.cpp, examples/code/liveernst/liveernst.cpp, examples/code/lua/lua.cpp, examples/code/materials/materials.cpp, examples/code/occlusion/occlusion.cpp, examples/code/pointcloud/pointcloud.cpp, examples/code/readback/readback.cpp, examples/code/renderstats/renderstats.cpp, examples/code/rnm/rnm.cpp, and examples/code/simple/simple.cpp.

ILBStatus ILBSetSkyLightTexture	(	ILBLightHandle	light,
		ILBTextureHandle	texture
	)

Sets a texture for a sky light.

The texture should be in Lat/Long format.
Only works for sky lights

Parameters

light	light to set texture on
texture	texture to use

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp, and examples/code/liveernst/liveernst.cpp.

ILBStatus ILBSetSkyLightTextureFilter	(	ILBLightHandle	light,
		float	filter
	)

Sets texture filter size for a sky light.

Only works for sky lights

Parameters

light	light to set filter size on
filter	the filter size to use

Returns: The result of the operation.

ILBStatus ILBSetSkyLightVolumeType	(	ILBLightHandle	light,
		ILBLightVolumeType	type
	)

Sets light volume type for a sky light.

Only works for sky lights

Deprecated:

Use ILBSetLightVolumeType() instead

Parameters

light	light to set light volume type on
type	the volume type to use

Returns: The result of the operation.

Examples:: examples/code/liveernst/liveernst.cpp.

ILBStatus ILBSetSpotlightCone	(	ILBLightHandle	light,
		float	angleRadians,
		float	penumbraAngleRadians,
		float	penumbraExponent
	)

Sets the cone angle for a spotlight.

The cone is given in radians for the entire cone (as opposed to the angle towards the forward direction). The penumbra angle is the angle from the edge of the cone over which the intensity falls off to zero. The effective spread of the cone is max( angleRadians, angleRadians + 2*penumbraAngleRadians ) since the penumbra angle can be both positive and negative. The default cone angle is PI / 2 (90 degrees), The default is penumbra angle 0 The default penumbra exponent is 1

Parameters

light	the light source to set cone angle for
angleRadians	the angle in radians for the cone
penumbraAngleRadians	the angle of the penumbra of the spot light. It's given as the difference from the cone angle and can be both negative and positive.
penumbraExponent	the exponent for the gradient in the penumbra

Returns: The result of the operation.

Examples:: examples/code/ernst/ernst.cpp, examples/code/lightsources/lightsources.cpp, examples/code/liveernst/liveernst.cpp, and examples/code/uvset/uvset.cpp.

Go to the source code of this file.

beastapi/beastlightsource.h File Reference

File Description

Typedefs

Enumerations

Functions

Typedef Documentation

Enumeration Type Documentation

Function Documentation