IPhysicalLightShape

Detailed Description

class IPhysicalLightShape : public RED::IREDObject 

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 call to RED::IPhysicalLightShape::SetLuminousFlux, RED::IPhysicalLightShape::SetPowerAndEfficacy or RED::IPhysicalLightShape::SetPowerAndEfficiency to setup light emission
a call to RED::IPhysicalLightShape::SetColor or RED::IPhysicalLightShape::SetTexture to setup the light color
a call to RED::IPhysicalLightShape::SetEmitter or RED::IPhysicalLightShape::SetEmitterSpherical to set the emitter shape

A physical light is approximated in realtime:

An area light is used if the physical light’s emitter mesh is a rectangle. See RED::ILightShape::SetRectangularAreaLight for all the details on the conversion.
A point light is used in all other configurations.

\task tk_setup_a_physical_light

For a more detailed tutorial about how to implement and use physical lights, please have a look at \ref wf_lighting_with_physical_lights.

Public Functions

virtual RED_RC SetLuminousFlux(float iLuminousFlux, 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 \ref tk_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.

virtual RED_RC GetLuminousFlux(float &oLuminousFlux, int iStateNumber = -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.

virtual RED_RC SetPowerAndEfficacy(float iPower, float iLuminousEfficacy, 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.

virtual RED_RC GetPowerAndEfficacy(float &oPower, float &oLuminousEfficacy, int iStateNumber = -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.

virtual RED_RC SetPowerAndEfficiency(float iPower, float iLuminousEfficiency, 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.

virtual RED_RC GetPowerAndEfficiency(float &oPower, float &oLuminousEfficiency, int iStateNumber = -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.

virtual RED_RC 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 RED::IPhysicalLightShape::SetIESMatrix if you wish to change the axis system of the IES internally to the light source.

See also \ref wf_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.

virtual RED_RC 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 \ref wf_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.

virtual RED_RC GetIES(RED::String &oFile, RED::Vector<double> &oValues, int iStateNumber = -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.

virtual RED_RC SetIESAngle(float iAngle, 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.

virtual RED_RC GetIESAngle(float &oAngle, int iStateNumber = -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.

virtual RED_RC SetIESMatrix(const RED::Matrix &iMatrix, const RED::State &iState) = 0

Overrides the default IES orientation matrix in the light’s local axis system.

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.

This method lets you change the axis system being used. By default, it’s the RED::Matrix::IDENTITY matrix, meaning that the IES lighting axis will be along -Z. By specifying another transformation matrix, here, the IES lighting axis will be along minus the third matrix column, and the two other orthogonal axises will complete the transform mapping.

Note that on turning the IES light, the visible area of the IES may no longer match the light’s mesh orientation since this method allows to just turn the IES axis system. Consequently, backface culling may occur if the light is not also set double sided or if its supporting mesh is not rotated accordingly.

Parameters

iMatrix – The new axis system for the IES lighting. In the light’s local axis system. Default is RED::Matrix::IDENTITY.
iState – The current transaction parameter.

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.

virtual RED_RC GetIESMatrix(RED::Matrix &oMatrix, int iStateNumber = -1) const = 0

Returns the matrix defined by RED::IPhysicalLightShape::SetIESMatrix.

Parameters

oMatrix – The current IES lighting matrix.
iStateNumber – The current transaction parameter.

Returns

RED_OK if the method has succeeded,

RED_BAD_PARAM if iStateNumber is invalid.

virtual RED_RC HasIES(bool &oIES, int iStateNumber = -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.

virtual RED_RC 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.

virtual RED_RC 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 \ref tk_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.

virtual RED_RC GetColor(RED::Color &oColor, int iStateNumber = -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.

virtual RED_RC SetTexture(const RED::Object *iTexture, const RED::Matrix &iTextureMatrix, RED::MESH_CHANNEL iUVChannel, 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 \ref wf_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.

virtual RED_RC GetTexture(const RED::Object *&oTexture, RED::Matrix &oTextureMatrix, RED::MESH_CHANNEL &oUVChannel, int iStateNumber = -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.

virtual RED_RC SetEmitter(RED::Object *iMesh, float iScale, 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 tk_controlling_visibility_of_a_physical_light_emitter

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.

virtual RED_RC SetEmitterSpherical(RED::Object *iMesh, float iScale, const RED::Vector3 &iDirection, float iAngle, 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 constrained to the cone of axis iDirection> and half-angle iAngle. Note that the falloff resulting of that spotlight term is sharp. To get smooth falloffs use IES profiles instead (see RED::IPhysicalLightShape::SetIES).

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 \ref wf_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.
iScale – scaling factor to convert mesh modeling units to meters.
iDirection – direction of the light (if spotlight), not necessarily a unit vector.
iAngle – half-angle of the spotlight (in radians); can’t be 0. If greater or equal to RED_PI2, an omni-directional light is set.
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.

virtual RED_RC GetEmitterSpherical(bool &oIsSpherical, RED::Vector3 &oPosition, float &oRadius, RED::Vector3 &oDirection, float &oAngle, int iStateNumber = -1) const = 0

Gets the spherical properties of the light.

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

Parameters

oIsSpherical – true if the light is spherical, false otherwise. If false is returned, remaining method parameters may contain undefined values.
oPosition – position of the light.
oRadius – radius of the light.
oDirection – unit direction of the light if spotlight.
oAngle – angle of the light if spotlight (in radians).
iStateNumber – queried state number.

Returns

RED_OK if the operation has succeeded,

RED_FAIL otherwise.

virtual RED_RC GetEmitterMesh(RED::Object *&oMesh, float &oScale, float &oArea, int iStateNumber = -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.

virtual RED_RC 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 \ref tk_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.

virtual RED_RC CreateSphericalEmitterMesh(RED::Object *&oMesh, float iSmoothness, float iRadius, 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

oMesh – valid pointer to the returned sphere mesh.
iSmoothness – smoothness of the tessellated sphere in the [0, 1] range. Maximum number of triangles for the sphere is 960 for iSmoothness = 1.f.
iRadius – radius of the sphere (in model units).
iState – current transaction.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid parameter,

RED_ALLOC_FAILURE on a memory allocation error,

RED_FAIL otherwise.

virtual RED_RC SetEmitterSphericalSpot(const RED::Vector3 &iDirection, float iAngle, 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

iDirection – axis of the spotlight cone.
iAngle – half-angle of the spotlight cone in the [0, Pi/2] interval (in radians).
iState – current transaction.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid parameter,

RED_ALLOC_FAILURE on a memory allocation error,

RED_FAIL otherwise.

virtual RED_RC SetSamplesCount(unsigned int iSamplesCount, 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.

virtual RED_RC GetSamplesCount(unsigned int &oSamplesCount, int iStateNumber = -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.

virtual RED_RC SetDoubleSided(bool iDoubleSided, 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.

virtual RED_RC IsDoubleSided(bool &oDoubleSided, int iStateNumber = -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 Static Functions

static inline RED::CID GetClassID()

CID	`GetClassID`
`RED_RC`	`SetLuminousFlux`
`RED_RC`	`GetLuminousFlux`
`RED_RC`	`SetPowerAndEfficacy`
`RED_RC`	`GetPowerAndEfficacy`
`RED_RC`	`SetPowerAndEfficiency`
`RED_RC`	`GetPowerAndEfficiency`
`RED_RC`	`SetIES`
`RED_RC`	`SetIESValues`
`RED_RC`	`GetIES`
`RED_RC`	`SetIESAngle`
`RED_RC`	`GetIESAngle`
`RED_RC`	`SetIESMatrix`
`RED_RC`	`GetIESMatrix`
`RED_RC`	`HasIES`
`RED_RC`	`ClearIES`
`RED_RC`	`SetColor`
`RED_RC`	`GetColor`
`RED_RC`	`SetTexture`
`RED_RC`	`GetTexture`
`RED_RC`	`SetEmitter`
`RED_RC`	`SetEmitterSpherical`
`RED_RC`	`GetEmitterSpherical`
`RED_RC`	`GetEmitterMesh`
`RED_RC`	`GetEmitterMaterial`
`RED_RC`	`CreateSphericalEmitterMesh`
`RED_RC`	`SetEmitterSphericalSpot`
`RED_RC`	`SetSamplesCount`
`RED_RC`	`GetSamplesCount`
`RED_RC`	`SetDoubleSided`
`RED_RC`	`IsDoubleSided`

IPhysicalLightShape

Functions

Detailed Description