class RED::IPhysicalLightShape

This interface gives access to physical lights creation and manipulation methods. More...

#include <REDIPhysicalLightShape.h>

Inherits: IREDObject.

Public functions:

virtual RED_RCClearIES ( const RED::State & iState ) = 0
virtual RED_RCCreateSphericalEmitterMesh ( RED::Object *& oMesh, float iSmoothness, float iRadius, const RED::State & iState ) const = 0
virtual RED_RCGetColor ( RED::Color & oColor, int iStateNumber = -1 ) const = 0
virtual RED_RCGetEmitterMaterial ( RED::Object *& oMaterial, const RED::State & iState ) = 0
virtual RED_RCGetEmitterMesh ( RED::Object *& oMesh, float & oScale, float & oArea, int iStateNumber = -1 ) const = 0
virtual RED_RCGetEmitterSpherical ( bool & oIsSpherical, RED::Vector3 & oPosition, float & oRadius, RED::Vector3 & oDirection, float & oAngle, int iStateNumber = -1 ) const = 0
virtual RED_RCGetIES ( RED::String & oFile, RED::Vector< double > & oValues, int iStateNumber = -1 ) const = 0
virtual RED_RCGetIESAngle ( float & oAngle, int iStateNumber = -1 ) const = 0
virtual RED_RCGetLuminousFlux ( float & oLuminousFlux, int iStateNumber = -1 ) const = 0
virtual RED_RCGetPowerAndEfficacy ( float & oPower, float & oLuminousEfficacy, int iStateNumber = -1 ) const = 0
virtual RED_RCGetPowerAndEfficiency ( float & oPower, float & oLuminousEfficiency, int iStateNumber = -1 ) const = 0
virtual RED_RCGetSamplesCount ( unsigned int & oSamplesCount, int iStateNumber = -1 ) const = 0
virtual RED_RCGetTexture ( const RED::Object *& oTexture, RED::Matrix & oTextureMatrix, RED::MESH_CHANNEL & oUVChannel, int iStateNumber = -1 ) const = 0
virtual RED_RCHasIES ( bool & oIES, int iStateNumber = -1 ) const = 0
virtual RED_RCIsDoubleSided ( bool & oDoubleSided, int iStateNumber = -1 ) const = 0
virtual RED_RCSetColor ( const RED::Color & iColor, const RED::State & iState ) = 0
virtual RED_RCSetDoubleSided ( bool iDoubleSided, const RED::State & iState ) = 0
virtual RED_RCSetEmitter ( RED::Object * iMesh, float iScale, const RED::State & iState ) = 0
virtual RED_RCSetEmitterSpherical ( RED::Object * iMesh, float iScale, const RED::Vector3 & iDirection, float iAngle, const RED::State & iState ) = 0
virtual RED_RCSetEmitterSphericalSpot ( const RED::Vector3 & iDirection, float iAngle, const RED::State & iState ) = 0
virtual RED_RCSetIES ( RED::Vector< RED::String > & oAttributes, const RED::String & iFile, const RED::State & iState ) = 0
virtual RED_RCSetIESAngle ( float iAngle, const RED::State & iState ) = 0
virtual RED_RCSetIESValues ( const RED::Vector< double > & iValues, const RED::String & iFile, const RED::State & iState ) = 0
virtual RED_RCSetLuminousFlux ( float iLuminousFlux, const RED::State & iState ) = 0
virtual RED_RCSetPowerAndEfficacy ( float iPower, float iLuminousEfficacy, const RED::State & iState ) = 0
virtual RED_RCSetPowerAndEfficiency ( float iPower, float iLuminousEfficiency, const RED::State & iState ) = 0
virtual RED_RCSetSamplesCount ( unsigned int iSamplesCount, const RED::State & iState ) = 0
virtual RED_RCSetTexture ( const RED::Object * iTexture, const RED::Matrix & iTextureMatrix, RED::MESH_CHANNEL iUVChannel, const RED::State & iState ) = 0

Public static functions:

static RED::CIDGetClassID ( )

Detailed description:

This interface gives access to physical lights creation and manipulation methods.

The RED::IPhysicalLightShape interface is exposed by CID_REDLightShape instances.

Real-life light emitters are defined by a set of physical values as well as a geometry. This interface lets you create virtual lights using those information available from light bulbs manufacturers.

You first need to create a light shape using the RED::Factory. Then you can ask for the RED::IPhysicalLightShape interface using the RED::IObject::As method. As a consequence a physical light can be turned into a non-physical one by using methods of the RED::ILightShape interface.

To describe the light emission, you can set the luminous flux (in lumens), the radiant flux (in Watts) with the luminous efficacy or efficiency, or an IES file.

The color of the light is defined using a RED::Color instance (which supports definition of color temperatures in Kelvin).

A mesh must be set to the light to define its geometrical source of emission. You can provide any mesh you want as long as it is made of triangles. You can also use the SetEmitterSpherical to make the light a perfect analytical sphere. In that case, sampling will be quicker and of better quality than using a tessellated sphere with SetEmitter.

On user request, a material with the same color property than the physical light can be retrieved to be applied to the light emitter mesh. Please see RED::IPhysicalLightShape::GetEmitterMaterial for details. Please note that the color of the material depends on the path of the light in the scene graph and depends on the transform applied to it. Incoherencies can be generated for lights that are instantiated so that different instances get different matrix transforms.

To have multiple instances of the same physical light, you just have to instantiate the underlying emitter mesh and keep a single instance of the physical light.

Physical lights do not support custom decays. Natural quadratic decay is the only supported mode and can't be turned off.

Shadows produced by physical light are ray-traced sampled shadows. Shadow mapping is not supported. However, you can still turn shadows off.

The emitter mesh is never deleted by the light. If the light points to an invalid mesh (the mesh was deleted but the light is not aware of for example), or has no mesh set, it will be ignored during the rendering.

In order to create a valid physical light, you need at least:

A physical light is approximated in realtime:

task

Task: Setup a physical light

Generic physical lights

There are three different physical lights in REDsdk: the sky, the sun and the generic one. We'll focus here on the third types. For the two others, please refer to the related pages.

You need to start with the creation of a light instance using the generic REDsdk shape creation mechanism (Creating and destroying shapes).

Then you have to retrieve the interface dedicated to physical lights:

// "phy" is a pointer to a REDsdk light instance.
RED::IPhysicalLightShape* iphy = phy->As< RED::IPhysicalLightShape >();

A physical light needs a base mesh to setup correctly. The base mesh is the shape of light emission. It also needs some physical values as the luminous flux or power (in lumens or Watts), the light colour and the scene units conversion factor (this is because computations are physically correct and need real world units to produce right values):

// "emitter" is a pointer to a valid triangle-based mesh in the scene.
// "scene_units_to_meters" is the conversion factor between scene units and meters.
RC_TEST( iphy->SetEmitter( emitter, scene_units_to_meters, iresmgr->GetState() ) );

For example, if your scene is modelled in feet, the scene units conversion factor should be set to 0.3048 because 1 foot = 0.3048 meter.

Ok, we've just setup the shape of the physical light emission. We now must set the light emission parameters: intensity, colour, distribution... Bulb manufacturers often give detailed information about their products including lumens and color temperature. Those values can be entered straight in REDsdk using the right API calls:

float luminous_flux = 1500.f;
RED::Color color = RED::Color::FromTemperature( 2700.f );
RC_TEST( iphy->SetLuminousFlux( luminous_flux, iresmgr->GetState() ) );
RC_TEST( iphy->SetColor( color, iresmgr->GetState() ) );

In order for the light mesh to render with the right colour and intensity, we can ask the light for a corresponding ready-to-use material and apply it to the geometry.


// Builds the emitter material.
RED::Object* emitter_material = NULL;
RC_TEST( iphy->GetEmitterMaterial( emitter_material, iresmgr->GetState() ) );

// Applies the emitter material to the corresponding emitter mesh.
RC_TEST( emitter->As< RED::IShape >()->SetMaterial( emitter_material, iresmgr->GetState() ) );

The colour of a physical light can also be textured-based. To do that, simply call RED::IPhysicalLightShape::SetTexture instead of SetColor on the light object. This can be useful to simulate back lighting screens for example.

A texture-based physical light.

We now have a fully featured omnidirectional light of 1500 lumens and 1700 Kelvin color temperature. For convenience, REDsdk also provides alternate ways of setting the light intensity using power and efficiency or efficacy (See RED::IPhysicalLightShape for details).

We can go a little further by adding a custom profile of emission to a light using standardized industrial data: IES files. Most of the bulb manufacturers provide measured IES files of their products. REDsdk is compatible with the LM-63-02 IES norm. It's easy to set an IES profile to an existing light:

RED::Vector< RED::String > ies_attributes;
const char* ies_file_path = "./resources/50w_light_bulb.ies";
RC_TEST( iphy->SetIES( ies_attributes, ies_file_path, iresmgr->GetState() ) );

The attributes stored in the IES profile are returned in a readable format in a vector of strings.

Finally, as for any other sampled light in REDsdk, the quality of the light rendering can be tuned by setting the light number of samples:

RC_TEST( iphy->SetSamplesCount( 64, iresmgr->GetState() ) );

Spherical physical lights

RED physical lights provide a special case of lights: spherical physical lights. Spherical lights are useful as they are very often encountered in real-life and are easier and quicker to render than more complex light shapes. To create a spherical physical light, just call:

// "emitter" is a pointer to a valid triangle-based mesh in the scene.
// "light_dir" is the main light direction if the light is a spot (ignored otherwise)
// "light_angle" is the light spot half-angle in radians if the light is a spot (ignored otherwise)
RC_TEST( iphy->SetEmitterSpherical( emitter, scene_units_to_meters, light_dir, light_angle, iresmgr->GetState() ) );

The passed mesh is used to represent the light in the scene but internally, the light shape will be an analytical sphere. The radius of that sphere is determined by computing the radius of the given mesh bounding sphere. As a bonus, a spherical physical light can also be a spot light without having to model the light panes. This is achieved by passing a main direction and half-angle to the method.

Three physical spherical lights; left: omnidirectional, middle: spot, right: with IES profile

For a more detailed tutorial about how to implement and use physical lights, please have a look at Lighting with physical lights.

Functions documentation

public virtual RED_RC RED::IPhysicalLightShape::ClearIES(const RED::State &iState) = 0

Clears the current IES profile of the light.

If the light has no profile set, the method does nothing.

Returns:

RED_OK if the operation has succeeded,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::CreateSphericalEmitterMesh(RED::Object *&oMesh,
floatiSmoothness,
floatiRadius,
const RED::State &iState
)const = 0

Creates a sphere mesh at the given resolution.

Use this helper to create a mesh for spherical emitters (SetEmitterSpherical).

The sphere has three channels set:

  • RED::MCL_VERTEX: sphere vertices (3 coordinates per entry)
  • RED::MCL_NORMAL: sphere vertex normals (3 coordinates per entry)
  • RED::MCL_TEX0: sphere vertex uv coordinates computed by spherical mapping (2 coordinates per entry)

The channels format is RED::FMT_FLOAT.

The returned sphere mesh in ioMesh becomes the property of the caller and must be deleted by him. This mesh is centered in (0, 0, 0), and has texture coordinates automatically computed using spherical mapping.

Parameters:

oMeshvalid pointer to the returned sphere mesh.
iSmoothnesssmoothness of the tessellated sphere in the [0, 1] range. Maximum number of triangles for the sphere is 960 for iSmoothness = 1.f.
iRadiusradius of the sphere (in model units).
iStatecurrent transaction.

Returns:

RED_OK on success,
RED_BAD_PARAM on an invalid parameter,
RED_ALLOC_FAILURE on a memory allocation error,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::GetColor(RED::Color &oColor,
intiStateNumber = -1
)const = 0

Gets the color of the light.

Parameters:

oColor:color of the emitted light.
iStateNumber:queried state number.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::GetEmitterMaterial(RED::Object *&oMaterial,
const RED::State &iState
) = 0

Gets a material matching the light setup.

Physical lights rely on meshes. This methods create a material which is consistent with the light setup (intensity, color) to be used to render the emitter mesh.

The first time the method is called, it creates and setup the material (oMaterial must be NULL). Then, the material is automatically updated each time a light parameter is changed. Each subsequent call to the method for the same light should use the previously returned material. An emitter mesh must have been set to the light before calling GetEmitterMaterial. Otherwise, the method will return RED_FAIL.

The color set in oMaterial depends on the light source properties and also on the transformation matrix applied to the emitter mesh of the light (the cumulated transform from the root of the scene down to the shape). Therefore changing a matrix transform in a parent node of the shape may cause the material to be wrong if the matrix transform scaling is modified. Translations and rotations don't change the material color, but scaling does change its color. In this case, the engine don't detect the change and its the responsibility of the application to update the material by calling GetEmitterMaterial again after a transform scale change.

Another consequence of this dependency on the global transform scaling is that two instances of the same emitter mesh but seen using transformation matrix with different scales can't both have the correct color set in the material: two different scaling transformation matrices generate two different colors, so we can't assign one unique color that work for both instances in the material.

If this scene configuration arise, GetEmitterMaterial return the color found for the first instance of the emitter mesh in the scene graph. To have the transform taken into consideration by the operation, the light source should be already linked to its parent in the scene graph.

See also Setup a physical light.

Parameters:

oMaterial:the emitter material.
iState:current transaction.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL if the emitter mesh is not a RED::IMeshShape object,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::GetEmitterMesh(RED::Object *&oMesh,
float &oScale,
float &oArea,
intiStateNumber = -1
)const = 0

Gets the emitter mesh.

Parameters:

oMesh:pointer to the emitter mesh.
oScale:scaling factor to convert mesh modeling units to meters.
oArea:emitter mesh area in m^2.
iStateNumber:queried state number.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::GetEmitterSpherical(bool &oIsSpherical,
RED::Vector3 &oPosition,
float &oRadius,
RED::Vector3 &oDirection,
float &oAngle,
intiStateNumber = -1
)const = 0

Gets the spherical properties of the light.

To retrieve the mesh properties of a spherical light, call GetEmitterMesh.

Parameters:

oIsSphericaltrue if the light is spherical, false otherwise. If false is returned, remaining method parameters may contain undefined values.
oPositionposition of the light.
oRadiusradius of the light.
oDirectionunit direction of the light if spotlight.
oAngleangle of the light if spotlight (in radians).
iStateNumberqueried state number.

Returns:

RED_OK if the operation has succeeded,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::GetIES(RED::String &oFile,
RED::Vector< double > &oValues,
intiStateNumber = -1
)const = 0

Gets the current light IES settings.

The oValues array contains the setup of the IES lamp. Some values can be retrieved using the corresponding index. For example, oValues[RED_IES_LUMENS] stores the luminous flux of the IES lamp.

Photometric data are stored starting at RED_IES_HEADER_SIZE:

oValues[RED_IES_HEADER_SIZE+0]: first candela value oValues[RED_IES_HEADER_SIZE+1]: second candela value and so on...

Parameters:

oFile:name of the IES profile in use.
oValues:lamps values read from the IES profile.
iStateNumber:queried state number.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::GetIESAngle(float &oAngle,
intiStateNumber = -1
)const = 0

Gets the overriden IES angle.

IES lights emit light in a cone defined by this half-angle. If the half-angle is RED_PI, the light is emitted in every direction around its position, otherwise light is emitted only in a sub-set of directions in the cone defined by the light direction and this angle.

By default, this method returns 0 for any IES profile and as long as the IES angle has not been overriden by a call to SetIESAngle.

To retrieve the value of the IES angle as set originally in the profile, you must parse the information returned by GetIES.

Parameters:

oAngle:value of the light cone half-angle as set with SetIESAngle.
iStateNumber:queried state number.

Returns:

RED_OK on success,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::GetLuminousFlux(float &oLuminousFlux,
intiStateNumber = -1
)const = 0

Gets the luminous flux of the light.

The method returns the correct luminous flux even if the light emission has been defined using one of the SetPowerAndEfficacy or SetPowerAndEfficiency methods.

See RED::IPhysicalLightShape::SetLuminousFlux for more details.

Parameters:

oLuminousFlux:the returned luminous flux in lumens.
iStateNumber:queried state number.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::GetPowerAndEfficacy(float &oPower,
float &oLuminousEfficacy,
intiStateNumber = -1
)const = 0

Gets the power and efficacy of the light.

See RED::IPhysicalLightShape::SetPowerAndEfficacy for details.

Parameters:

oPower:power of the light in Watts.
oLuminousEfficacy:luminous efficacy of the light in lumens per Watts (lm/W).
iStateNumber:queried state number.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::GetPowerAndEfficiency(float &oPower,
float &oLuminousEfficiency,
intiStateNumber = -1
)const = 0

Gets the power and efficiency of the light.

See RED::IPhysicalLightShape::SetPowerAndEfficiency for details.

Parameters:

oPower:power of the light in Watts.
oLuminousEfficiency:luminous efficiency of the light in percentage (%).
iStateNumber:queried state number.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::GetSamplesCount(unsigned int &oSamplesCount,
intiStateNumber = -1
)const = 0

Gets the number of light samples.

See RED::IPhysicalLightShape::SetSamplesCount for details.

Parameters:

oSamplesCount:the maximum number of light samples.
iStateNumber:queried state number.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::GetTexture(const RED::Object *&oTexture,
RED::Matrix &oTextureMatrix,
RED::MESH_CHANNEL &oUVChannel,
intiStateNumber = -1
)const = 0

Gets the texture of the light.

See RED::IPhysicalLightShape::SetTexture for details.

Parameters:

oTexture:texture of the emitted light color.
oTextureMatrix:texture transformation matrix.
oUVChannel:uv channel to be used with the emitter mesh.
iStateNumber:queried state number.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::HasIES(bool &oIES,
intiStateNumber = -1
)const = 0

Checks if the light has an IES profile set.

Parameters:

oIES:true if the light has an IES profile set, false otherwise.
iStateNumber:queried state number.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::IsDoubleSided(bool &oDoubleSided,
intiStateNumber = -1
)const = 0

Is the light double sided?

See RED::IPhysicalLightShape::SetDoubleSided for details.

Parameters:

oDoubleSided:true if the light is double sided, false otherwise. false otherwise.
iStateNumber:queried state number.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::SetColor(const RED::Color &iColor,
const RED::State &iState
) = 0

Sets the color of the light.

Most manufacturers express the color of their bulbs in Kelvin. You can use the RED::Color::FromTemperature method to convert a color temperature into a RED::Color instance.

See also Setup a physical light.

Parameters:

iColor:color of the emitted light.
iState:current transaction.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::SetDoubleSided(booliDoubleSided,
const RED::State &iState
) = 0

Sets to true to make the light emits on both sides, set to false otherwise.

Parameters:

iDoubleSided:true to make the light emits on both sides, false otherwise.
iState:current transaction.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::SetEmitter(RED::Object *iMesh,
floatiScale,
const RED::State &iState
) = 0

Sets a custom light emitter.

As long as no mesh has been set, the light is considered disabled by the engine, except if the light is spherical (see RED::IPhysicalLightShape::SetEmitterSpherical).

The caller must supply the scaling factor to convert the mesh units to meters as it is necessary for proper physical lighting computations. For example, if the scene units are feet, the scaling factor should be set to 0.3048 (1 foot = 0.3048 meter).

The mesh can be of any shape as long as it is made of triangles.

The light doesn't become the owner of the mesh: when the light is deleted the mesh is not deleted.

Note that you can make the emitter geometry invisible while the light is still contributing to the scene.

task

Task: Controlling visibility of a physical light emitter

Depending of the usage of a physical light, one may want to make it invisible to the viewer. For example, rectangular physical lights can be used at interior scene windows to simulate light coming from the outside. However, the viewer still wants to see the garden through the windows rather than the light panels.

Here is how you can show/hide physical light emitters:

// "light" is a pointer to a REDsdk physical light instance.
// "visible" is a boolean set to true if the light should be visible, to false otherwise.
RED::ILightShape* ilight = light->As< RED::ILightShape >();
RC_TEST( ilight->SetRenderMode( RED::RM_VISIBLE_GEOMETRY, visible ? 1 : 0, iresmgr->GetState() ) );

The same scene with the emitter visible on the left and hidden on the right.

Parameters:

iMesh:pointer to the mesh to be set as the source of light emission (can't be NULL).
iScale:scaling factor to convert mesh modeling units to meters.
iState:current transaction.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::SetEmitterSpherical(RED::Object *iMesh,
floatiScale,
const RED::Vector3 &iDirection,
floatiAngle,
const RED::State &iState
) = 0

Sets a spherical physical light.

This method is a helper which assists you in setting a perfect spherical physical light (analytical sphere light).

This helper works by finding the bounding sphere of the supplied mesh and use it as the source of light distribution. Using that analytical sphere instead of the mesh triangles for light sampling ensures a better quality, quicker. Hence, if you know your light is approximatively a sphere, you are strongly encouraged to use the method instead of the more generic SetEmitter one.

When the analytical sphere is computed, texture coordinates using spherical mapping are automatically computed. So, you can use SetTexture along with SetEmitterSpherical to create textured spherical lights.

The influence of the spherical light can be reduced by providing a spot half-angle in radians. The light emission will then be constraint to the cone of axis iDirection and half-angle iAngle.

The iDirection of the light is relative to the light coordinates system.

The caller must supply the scaling factor to convert the mesh units to meters as it is necessary for proper physical lighting computations. For example, if the scene units are feet, the scaling factor should be set to 0.3048 (1 foot = 0.3048 meter).

If an IES file is used with a spherical light, it overrides the light direction and angle.

The light doesn't become the owner of the mesh: when the light is deleted the mesh is not deleted.

To revert from a spherical light, just call SetEmitter on it with the new light shape.

See also Lighting with physical lights.

Parameters:

iMesh:pointer to the emitter mesh. The mesh will have no influence on the light distribution and will be used only for light visualization.
iScalescaling factor to convert mesh modeling units to meters.
iDirectiondirection of the light (if spotlight), not necessarily a unit vector.
iAnglehalf-angle of the spotlight (in radians); can't be 0. If greater or equal to RED_PI2, an omni-directional light is set.
iStatecurrent transaction.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::SetEmitterSphericalSpot(const RED::Vector3 &iDirection,
floatiAngle,
const RED::State &iState
) = 0

Sets the spot parameters of a spherical physical light.

If the light is not a spherical one, the call returns RED_FAIL.

If the provided half-angle is bigger than Pi/2, the light will be considered as omnidirectional.

Parameters:

iDirectionaxis of the spotlight cone.
iAnglehalf-angle of the spotlight cone in the [0, Pi/2] interval (in radians).
iStatecurrent transaction.

Returns:

RED_OK on success,
RED_BAD_PARAM on an invalid parameter,
RED_ALLOC_FAILURE on a memory allocation error,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::SetIES(RED::Vector< RED::String > &oAttributes,
const RED::String &iFile,
const RED::State &iState
) = 0

Sets the IES profile of the light.

Manufacturers measure the behavior of their bulbs and store their directional contribution into IES files. Those files are available for most of the bulb models directly from the manufacturers' web sites.

IES files also store information about the emitted energy of the lamp. This information does not override the emitted energy set by the user which remains unchanged after a call to SetIES. However, you can retrieve the IES lamp luminous flux by looking at the values returned by GetIES.

Even if IES files store information about the shape of the emitter, they are not used here. It's the emitter mesh, set through SetEmitter or SetEmitterSpherical, which defines the spatial distribution of light. So, try to set meshes which respect the shape of the lamps used to extract IES information as well as their dimensions.

The method returns the list of the IES file attributes stored as (keyword, value, keyword, value, ...)

Officialy supported IES file format is LM-63-02. Only photometric data of Type C (most common type) are supported.

The IES main lighting axis (as defined by the IES LM-63-02 format) must be aligned with the -Z axis of the light source. Therefore, this corresponds to the -right axis of the light in the REDsdk default local axis system for light sources.

See also Lighting with physical lights.

Parameters:

oAttributes:list of the returned IES file attributes.
iFile:full path to the IES file to be loaded.
iState:current transaction.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FILE_NOT_FOUND when the file could not be found using iFile,
RED_ACCESS_DENIED when the file could not be accessed with the requested rights,
RED_FILE_DATA_ERROR if the file does not complies to IES LM-63-02 specifications,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::SetIESAngle(floatiAngle,
const RED::State &iState
) = 0

Overrides the IES angle with a custom one.

IES files store everything you need to know about the shape of light emission from a given bulb. However, in some cases, it may be useful to modify this shape of emission by specifying a custom angle value to make the light cone wider or narrower.

This method lets you do that by giving the half-angle of emission around the light direction.

To revert to the original shape of emission as defined in the IES profile, just call the method passing 0 as the angle.

If the passed angle is greater than RED_PI, RED_PI will be used instead (producing omni directional lighting).

Parameters:

iAngle:half-angle of the light emission cone around the light direction (in radians).
iState:current transaction.

Returns:

RED_OK on success,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::SetIESValues(const RED::Vector< double > &iValues,
const RED::String &iFile,
const RED::State &iState
) = 0

Sets the IES profile of the light by providing its values.

For details about IES, please see RED::IPhysicalLightShape::SetIES.

See also Lighting with physical lights.

The list of values can be retrieved with RED::IPhysicalLightShape::GetIES after having set a valid IES file.

The file iFile doesn't need to be found on the system since the values are directly used.

Parameters:

iValues:list of the values.
iFile:full path to the IES file where those values come from.
iState:current transaction.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::SetLuminousFlux(floatiLuminousFlux,
const RED::State &iState
) = 0

Sets the light luminous flux in lumens.

The luminous flux expresses the quantity of visible light emitted by the source. The information is provided by most manufacturers on the bulb packages.

See also Setup a physical light.

Parameters:

iLuminousFlux:the luminous flux in lumens.
iState:current transaction.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::SetPowerAndEfficacy(floatiPower,
floatiLuminousEfficacy,
const RED::State &iState
) = 0

Sets the power and efficacy of the light.

Light emission can be described by its power. It includes all the emitted energy (not only visible one) and we must therefore take the efficacy (or efficiency) of the light into account in order to compute its real contribution to perceived lighting.

The maximum efficacy of a light is 683 lm/W which corresponds to a 100% efficiency. Values greater than 683 will return RED_BAD_PARAM.

Parameters:

iPower:power of the light in Watts.
iLuminousEfficacy:luminous efficacy of the light in lumens per Watts (lm/W).
iState:current transaction.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::SetPowerAndEfficiency(floatiPower,
floatiLuminousEfficiency,
const RED::State &iState
) = 0

Sets the power and efficiency of the light.

Light emission can be described by its power. It includes all the emitted energy (not only visible one) and we must therefore take the efficiency (or efficacy) of the light into account in order to compute its real contribution to perceived lighting.

The maximum efficiency of a light is 100% which corresponds to a 683 lm/W efficacy. Values greater than 100 will return RED_BAD_PARAM;

Parameters:

iPower:power of the light in Watts.
iLuminousEfficiency:luminous efficiency of the light in percentage (%).
iState:current transaction.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::SetSamplesCount(unsigned intiSamplesCount,
const RED::State &iState
) = 0

Sets the number of samples to be taken during light evaluation.

Physical lights are sampled during the rendering phase in each shaded point to estimate their contribution to the scene. The more the samples, the better the result and the longer the rendering times.

Lights can't have less than 1 sample. If 0 is supplied, 1 will be used instead.

Parameters:

iSamplesCount:maximum number of samples to be taken while evaluating the light contribution.
iState:current transaction.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IPhysicalLightShape::SetTexture(const RED::Object *iTexture,
const RED::Matrix &iTextureMatrix,
RED::MESH_CHANNELiUVChannel,
const RED::State &iState
) = 0

Sets the texture of the light.

Rather than using a single constant color for the whole light, you can setup a texture from which light color will be read. Using a texture, you can simulate projectors or complex light filters.

If the texture is set to NULL, the light color will be used instead.

Only 2D images (implementing the RED::IImage2D interface) are supported.

See also Lighting with physical lights.

Parameters:

iTexture:texture of the emitted light color.
iTextureMatrix:texture transformation matrix.
iUVChannel:uv channel to be used with the emitter mesh.
iState:current transaction.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.