ISoftRayContext
Functions
void |
|
int |
|
int |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
bool |
|
void |
|
double |
|
void |
|
void |
|
int |
|
int |
|
int |
|
void |
|
void |
|
void |
|
Object * |
|
const ShapePath & |
|
Object * |
|
Matrix * |
|
LayerSet * |
|
double |
|
double |
|
bool |
|
bool |
|
bool |
|
bool |
|
bool |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
const ISoftLight * |
|
const Object * |
|
bool |
|
const Object * |
|
const Matrix * |
|
const Matrix * |
|
double |
|
unsigned int |
|
bool |
|
bool |
Detailed Description
-
class ISoftRayContext : public RED::IREDObject
Define read-only access methods to the context of a soft tracer ray.
@related The CPU Programming Pipeline, Writing a Custom Software Rendering Shader, class RED::ISoftRenderingContext, class RED::ISoftShaderContext
This interface is retrieved from a RED::SOFT_SHADER_CALLBACK, and contains all the informations that are accessible for the current ray that is being processed by the software ray-tracer.
Public Functions
-
virtual void GetPixelCoordinates(double oPixel[2]) const = 0
Gets the coordinates of the pixel through which the first ray of the stack has been sent.
- Parameters
oPixel – Returned 2D vector containing the pixel coordinates.
-
virtual int GetDepth() const = 0
- Returns
The depth we’re at in the ray-tree.
-
virtual int GetThreadID() const = 0
- Returns
the ID of the thread owning the ray context.
-
virtual void Interpolate(double oInterpolated[4], const RED::RenderCode &iRenderCode, RED_VSH_INPUT iChannel) const = 0
Calculates interpolated mesh parameters at the current hit point.
This method may renormalize resulting interpolated values based on the ‘iRenderCode’ specification.
If we’re shading a custom geometry, then we have no mesh and the geometrical data input is sourced from the shading callback in use (see the RED::SOFT_RAY_PROCESSING_SHADING_CALLBACK). In this case, any channel renormalization can’t be done by the interpolate method and it must be done beforehand in the shading callback.
- Parameters
iRenderCode – The binding specification.
iChannel – The channel to interpolate.
oInterpolated – The interpolated value.
-
virtual void Interpolate(double oInterpolated[4], RED::MESH_CHANNEL iMeshChannel) const = 0
Calculates interpolated mesh parameters at the current hit point.
This method does not renormalize resulting interpolated values.
If we’re shading a custom geometry, then we have no mesh and the geometrical data input is sourced from the shading callback in use (see the RED::SOFT_RAY_PROCESSING_SHADING_CALLBACK). In this case, any channel renormalization can’t be done by the interpolate method and it must be done beforehand in the shading callback.
- Parameters
iMeshChannel – The mesh channel source to interpolate.
oInterpolated – The interpolated value.
-
virtual void GetWCSHit(double oWCSHit[4]) const = 0
Gets the WCS hit point.
Converts the ray hit point in WCS and return it. The result vector is in 4d.
- Parameters
oWCSHit – The hit point in WCS (a four floats array).
-
virtual void GetWCSNormal(double oWCSNormal[4], const RED::RenderCode &iRenderCode, RED_VSH_INPUT iChannel = RED_VSH_NORMAL) const = 0
Gets the WCS normal at the hit point.
Interpolates the ‘iChannel’ channel at the hit point coordinates and turns it in WCS using the hit instance matrix. The result vector is in 4d.
- Parameters
iRenderCode – The binding specification.
oWCSNormal – The WCS normal at the hit point (a four floats array).
iChannel – The channel to use to lookup the normal.
-
virtual void GetWCSTangent(double oWCSTangent[4], const RED::RenderCode &iRenderCode, RED_VSH_INPUT iChannel = RED_VSH_COLOR) const = 0
Gets the WCS tangent at the hit point.
Interpolates the ‘iChannel’ channel at the hit point coordinates and turns it in WCS using the hit instance matrix.
- Parameters
iRenderCode – The binding specification.
oWCSTangent – The WCS tangent at the hit point (4 floats array).
iChannel – The channel to use to lookup the tangent.
-
virtual void GetWCSIncoming(double oWCSIncoming[4]) const = 0
Returns the incoming vector.
This is the vector from the ray origin to the ray intersection in World Coordinate Space (WCS).
- Parameters
oWCSIncoming – The vector from the ray origin to the intersection. The vector is not normalized and in WCS (4 floats).
-
virtual bool HasDifferentials() const = 0
- Returns
true if the ray has differentials, false otherwise.
-
virtual void GetWCSDifferentials(double oWCSdPdX[4], double oWCSdPdY[4]) const = 0
Returns the ray differentials in x and y.
- Parameters
oWCSdPdX – ray differential in x in world space (dP/dX).
oWCSdPdY – ray differential in y in world space (dP/dY).
-
virtual double GetNormalFacing() const = 0
Checks the facing of the eye vector against the hit triangle normal.
- Returns
+1.0f if we are front facing the hit triangle; -1.0f otherwise.
-
virtual void GetPrimaryPixelFrustum(double oFrustumPlanes[24]) const = 0
Gets the geometrical frustum defined by a pixel.
This method returns the geometrical coordinates of a primary pixel frustum. The frustum is the truncated pyramid fired from the camera eye that cover the pixel screen. It’s illustrated in the image below:
- Parameters
oFrustumPlanes – 6 planes equations with 4 coefficients each [ a, b, c, d ], defining the plane equation: [ a*X + b*Y + c*Z + d = 0.0 ] are returned for a total of 24 values in the following order: far, bottom, top, right, left, near. Hence, the far frustum plane is defined by values 0-3, the bottom plane is defined by values 4-7 and so on.
-
virtual void GetHitInterval(double &oTMin, double &oTMax) const = 0
Gets the parametric hit interval of the primitive on the ray or frustum.
For a ray propagation (ray bounces at depth > 0 for standard images), this method returns the parametric length of the hit point along the propagated ray. In this configuration, ‘oTMin’ and ‘oTMax’ are identical and set to this unique value.
For a frustum propagation (case of a pixel analytics query), this method returns the parametric boundaries (as a z-buffer depth) of the intersection of the primitive with the propagated frustum. ‘oTMin’ corresponds to the closest hit point of the hit primitive with the frustum; ‘oTMax’ corresponds to the farthest hit point of the same primitive with the frustum.
- Parameters
oTMin – Parametric interval of the hit primitive.
oTMax – Parametric interval of the hit primitive.
-
virtual int GetObjectUID() const = 0
Gets the object unique ID (UID) of the hit object.
The UID is the unique identifier for the hit object. This means that two instances of the same shape object have different unique IDs assigned by the engine. If the hit primitive is a custom primitive, then there’s no valid UID stored in the engine database for the hit object. In this case, the returned UID is -1.
- Returns
The object UID.
-
virtual int GetElementUID() const = 0
Gets the hit element of the hit object unique ID (UID).
The UID is the unique identifier for the hit element in the hit object. Two different triangles in a mesh have different UIDs. The two meshes objects themselves have different UIDs, returned by RED::ISoftRayContext::GetObjectUID.
If the hit primitive is a custom primitive, the returned hit element is -1.
-
virtual int GetObjectElementNumber() const = 0
Retrieves the number of the hit element in the hit object.
The returned number is either the number of the triangle, line segment, line strip or point in the hit shape instance.
If the hit primitive is a custom primitive, the returned hit element number is -1.
- Returns
The hit Object element number.
-
virtual void GetObjectElementIndices(int &oI0, int &oI1, int &oI2) const = 0
Retrieves the hit element mesh indices in the hit object.
This method returns the hit element indices in the hit object. For a triangle, this means the triangle three vertex indices [ oI0, oI1, oI2 ]; for a line strip or segment, this means two vertex indices [ oI0, oI1, -1 ]; for a point, only one vertex index is returned: [ oI0, -1, -1 ].
In the case of a custom primitive hit, the returned element indices are all -1.
- Parameters
oI0 – Index of the first vertex of the hit element in the hit object instance.
oI1 – Index of the second vertex of the hit element in the hit object instance.
oI2 – Index of the third vertex of the hit element in the hit object instance.
-
virtual void GetObjectElementUVs(double &oU, double &oV) const = 0
Retrieves the hit element mesh intersection UVs in the hit object.
This method returns the hit element intersection UVs in the hit object. For a triangle, this means that these UVs can be used to reconstruct the hit point, using P0 + oU*P0P1 + oV*P0P2. For a line element, the reconstruction is P0 + oU*P0P1; oV is undefined. For a point, oU and oV are undefined. In the case of a custom primitve, the returned values are undefined.
- Parameters
oU – Intersection UVs of the hit element in the hit object.
oV – Intersection UVs of the hit element in the hit object.
-
virtual void GetObjectElementWCS(double oP0[4], double oP1[4], double oP2[4]) const = 0
Retrieves the WCS vertices of the hit element in the hit object.
This method directly returns the WCS positions of the vertices that define the hit element in the hit object. The third vertex is set to [ 0.0 ] for a line and the second and third vertices are set to [ 0.0 ] for a point.
In the case of a custom primitive hit, all element hit coordinates are set to 0.0.
- Parameters
oP0 – First vertex of the hit element in the hit object instance.
oP1 – Second vertex of the hit element in the hit object instance.
oP2 – Third vertex of the hit element in the hit object instance.
-
virtual RED::Object *GetObjectShape() const = 0
Retrieves the shape object of the hit object.
In the case of a custom primitive hit, the returned shape address is NULL.
- Returns
The address of the shape of the hit object.
-
virtual const RED::ShapePath &GetObjectShapePath() const = 0
Retrieves the shape path of the hit object.
In the case of a custom primitive hit, the returned shape path is empty.
- Returns
A reference on the internal shape path associated to the hit shape instance.
-
virtual RED::Object *GetObjectMaterial() const = 0
Retrieves the shape material for this instance of the hit object.
Retrieve the material to use to display the hit object. The material being returned is calculated based on the DAG hierarchy in the scene and material inheritance rules. The last material on the path from the root of the scene down to the object instance is returned.
In the case of a custom primitive hit, the returned material address is the one that was returned by the SOFT_RAY_PROCESSING_SHADING_CALLBACK.
- Returns
The material address.
-
virtual RED::Matrix *GetObjectMatrix() const = 0
Retrieves the shape matrix for this instance of the hit object.
The returned matrix is the cumulated matrix on the path from the root of the scene down to the hit object instance.
In the case of a custom primitive hit, the returned matrix is NULL.
- Returns
The matrix to apply for this object. NULL if there’s no transform.
-
virtual RED::LayerSet *GetObjectLayerSet() const = 0
Retrieves the shape RED::LayerSet for this instance of the hit object.
The returned layerset is the last layerset found on the path from the root of the scene down to the hit object instance, according to the inheritance rules in use for the scene graph.
In the case of a custom primitive hit, the returned layerset is NULL.
- Returns
The RED::LayerSet to apply for this object. NULL if there’s no layerset.
-
virtual double GetIOR() const = 0
Gets the index of refraction (IOR) of the hit material.
- Returns
the index of refraction (IOR) of the hit material.
-
virtual double GetNextIOR() const = 0
Gets the index of refraction (IOR) of the next material in the ray tree.
- Returns
the index of refraction (IOR) of the next material in the ray tree.
-
virtual bool IsIOROnly() const = 0
Queries for the ray direction shader to return the IOR.
Calling this method disables the IOR only flag automatically.
- Returns
true if the shader can only return the IOR.
-
virtual bool IsShadingNormalOnly() const = 0
Queries for the ray direction shader to return the shading normal.
The shading normal is the interpolated normal at the current intersection point after having applied bump or displacement transformations.
Calling this method disables the shading normal only flag automatically.
- Returns
true if the shader can only return the support vector.
-
virtual bool IsNoBumpNormalOnly() const = 0
Queries for normal direction composites to return a non bumpy normal only.
If this method returns true, then the next normal calculation must ignore any bump mapping contribution.
Calling this method disables the ‘no bump normal’ flag automatically.
- Returns
true if the shader needs to compute a non bumpy normal.
-
virtual bool IsTangentOnly() const = 0
Queries for normal direction composites to return a tangent vector.
If this method returns true, then the next normal calculation must return the tangent vector at the calculated point.
Calling this method disables the ‘tangent only’ flag automatically.
- Returns
true if the shader needs to compute a tangent vector instead of a normal.
-
virtual bool IsGlossinessAnglesOnly() const = 0
Queries for the ray reflection shader to return glossiness values only.
If this method returns true, then the shader must return the glossiness angles to be used.
- Returns
true if the shader needs to retrive glossiness angles.
-
virtual void GetReflectionColor(double oColor[4]) const = 0
Gets the color of the reflection ray.
- Parameters
oColor – color of the reflection ray.
-
virtual void GetReflectionDistance(double &oDistance) const = 0
Gets the distance to the reflected surface.
The distance is returned in model units. If no surface is reflected DBL_MAX is returned.
- Parameters
oDistance – distance to the reflected surface.
-
virtual void GetRefractionColor(double oColor[4]) const = 0
Gets the color of the refraction ray.
- Parameters
oColor – color of the refraction ray.
-
virtual void GetRefractionDistance(double &oDistance) const = 0
Gets the distance to the refracted surface.
The distance is returned in model units. If no surface is refracted DBL_MAX is returned.
- Parameters
oDistance – distance to the refracted surface.
-
virtual void GetCutoff(double oCutoff[4]) const = 0
Gets the ray cutoff information.
- Parameters
oCutoff – the ray cutoff information.
-
virtual RED_RC GetShadowColor(double oShadowColor[4], const RED::ISoftLight *iLight, const RED::ISoftRenderingContext &iRenderCtx, const double *iSamplePos = NULL, int iSampleTID = 0, bool iForceTwoSided = false) const = 0
Casts a shadow ray from the hit point toward another point.
The ray is cast along the specified path (from the light source position or iSamplePos to the current hit position) until it gets fully blocked by a shadow caster or until it reaches its destination. The result color is in 4d.
- Parameters
oShadowColor – the returned shadow color (4d color).
iLight – The light source data record.
iRenderCtx – Global scene rendering context.
iSamplePos – Optional position on the light source (if the light has an area).
iSampleTID – Optional ID of the source triangle.
iForceTwoSided – Set to true if the shadow calculations have to force all materials to be two sided.
-
virtual void GetGlossySampleDir(double oSampleDir[3]) const = 0
Gets a sampling direction for glossiness.
This method returns a normalized direction in the cone defined by the material glossiness angle parameter. Each time the method is called, a new sampling direction is returned.
- Parameters
oSampleDir – the returned sampling direction.
-
virtual void SampleTexture(double oColor[4], int iColorBind, int iTextureBind, RED_VSH_INPUT iUVChannel, int iUVMatrixBind, const RED::ISoftShaderContext &iShaderContext, const RED::ISoftRenderingContext &iRenderContext) const = 0
Samples a color or a texture.
If the texture is valid, the method will sample it using the provided interpolation channel. Otherwise, the color is returned. The method handles composite textures as well.
- Parameters
iColorBind – Color parameter binding position. If there’s no valid binding position (<0), the method returns the black color.
iTextureBind – Texture binding channel.
iUVChannel – RED::Rendercode channel bound for this texture.
iUVMatrixBind – Binding position of the UV transform matrix.
iShaderContext – The shader parameters with our source information.
iRenderContext – Global rendering context.
oColor – The color to use.
-
virtual void SampleTexture(double oColor[4], int iTextureBind, RED_VSH_INPUT iUVChannel, int iUVMatrixBind, const double iColor[4], const RED::ISoftShaderContext &iShaderContext, const RED::ISoftRenderingContext &iRenderContext) const = 0
Samples a color or a texture.
If the texture is valid, the method will sample it using the provided interpolation channel. Otherwise, the color is returned. The method handles composite textures as well.
- Parameters
oColor – The color to use.
iColor – Color that is returned if we have no valid texture.
iTextureBind – Texture binding channel.
iUVChannel – RED::Rendercode channel bound for this texture.
iUVMatrixBind – Binding position of the UV transform matrix.
iShaderContext – The shader parameters with our source information.
iRenderContext – Global rendering context.
-
virtual void SampleTexture(double oColor[4], int iColorBind, int iTextureBind, const double iUV[4], const RED::Matrix &iUVMatrix, const RED::ISoftShaderContext &iShaderContext, const RED::ISoftRenderingContext &iRenderContext) const = 0
Samples a color or a texture.
If the texture is valid, the method will sample it using the provided uv coordinates. Otherwise, the color is returned. The method handles composite textures as well.
- Parameters
oColor – The resulting color.
iColorBind – Color parameter binding position. If there’s no valid binding position (<0), the method returns the black color.
iTextureBind – Texture binding channel.
iUV – UV coordinates of the texel.
iUVMatrix – UV transform matrix.
iShaderContext – The shader parameters with our source information.
iRenderContext – Global rendering context.
-
virtual void SampleTexture(double oColor[4], const RED::Object *iTexture, RED::MESH_CHANNEL iUVChannel, const RED::Matrix &iUVMatrix, const RED::ISoftShaderContext &iShaderContext, const RED::ISoftRenderingContext &iRenderContext) const = 0
Samples a texture.
- Parameters
oColor – The resulting color.
iTexture – The texture to sample.
iUVChannel – RED::Rendercode channel bound for this texture.
iUVMatrix – Texture matrix.
iShaderContext – The shader parameters with our source information.
iRenderContext – Global rendering context.
-
virtual void SampleTexture(double oColor[4], const RED::Object *iTexture, const double iUV[4], const RED::ISoftShaderContext &iShaderContext, const RED::ISoftRenderingContext &iRenderContext) const = 0
Samples a texture.
- Parameters
oColor – The resulting color.
iTexture – The texture to sample.
iUV – UV coordinates of the texel.
iShaderContext – The shader parameters with our source information.
iRenderContext – Global rendering context.
-
virtual void SampleNormalMap(double oBumpNormalWCS[4], double oNormalWCS[4], double oTangentWCS[4], int iTextureBind, RED_VSH_INPUT iUVChannel, RED_VSH_INPUT iNormalChannel, RED_VSH_INPUT iTangentChannel, int iUVMatrixBind, const RED::ISoftShaderContext &iShaderContext, const RED::ISoftRenderingContext &iRenderContext) const = 0
Samples a normal map or a displacement map. Returns the WCS normal vector.
If there’s no normal map texture or if there’s no displacement map, the method will return the interpolated world space normal.
- Parameters
oBumpNormalWCS – The perturbed normal direction in world space.
oNormalWCS – The normal before perturbation in world space.
oTangentWCS – The tangent in world space.
iTextureBind – Normal map binding channel.
iUVChannel – RED::Rendercode channel bound for this texture.
iNormalChannel – RED::Rendercode channel for accessing vertex normals.
iTangentChannel – RED::Rendercode channel for accessing vertex tangents.
iUVMatrixBind – Binding position of the UV transform matrix.
iShaderContext – The shader parameters with our source information.
iRenderContext – Global rendering context.
-
virtual void SampleFontGlyphTexture(double oColor[4], RED_VSH_INPUT iUVChannel, const RED::ISoftShaderContext &iShaderContext, const RED::ISoftRenderingContext &iRenderContext) const = 0
Samples a text glyph texture.
This method can be used to sample a text’s font glyph texture. The current hit primitive must be a text using the RED::FNT_TEXTURE rendering mode.
- Parameters
oColor – The resulting color.
iUVChannel – Channel holding text string glyph UVs.
iShaderContext – The shader parameters with our source information.
iRenderContext – Global rendering context.
-
virtual void SampleBackgroundImage(double oColor[4], const double iE[4], const double iP[4], bool iDirect, const RED::ISoftRenderingContext &iRenderContext) const = 0
Background image texture sampling.
See RED::IViewpointRenderList::SetBackgroundImages for the detail on all sampling configurations. The source pixel coordinates used to sample the 2D background image are directly sourced from RED::ISoftRayContext::GetPixelCoordinates, that are set on the ray launch.
- Parameters
oColor – Resulting texture color.
iE – Ray starting position.
iP – Ray ending position.
iDirect – If true, we consider the ray as a direct ray and we may use a screen space sampling if we have a 2D background image. If false, the cube image will be used.
iRenderContext – Rendering context.
-
virtual RED_RC PrepareLights(const double *iPoint, const double *iNormal, bool iIncludeBakedLights, const RED::ISoftRenderingContext &iRenderContext) const = 0
Prepares lights for the rendering at a given point in space by precomputing some values and discarding meaningless lights.
This call is mandatory before calling RED::ISoftRayContext::GetLights. It setups all lights, lighting parameters and culling functions needed to shade the point defined by ‘iPoint’ and ‘iNormal’.
- Parameters
iPoint – Current point being shaded, WCS.
iNormal – Current normal at the shaded point (optional).
iIncludeBakedLights – If true, baked lights are returned in the list. If false, baked lights are discarded and won’t appear in the list of lights.
iRenderContext – The rendering context.
- Returns
RED_OK if the operation has succeeded,
RED_ALLOC_FAILURE if a memory allocation has failed,
RED_FAIL otherwise.
-
virtual const RED::ISoftLight *GetLight(const RED::ISoftRenderingContext &iRenderContext) const = 0
Retrieves the current light to be rendered.
- Parameters
iRenderContext – The rendering context.
- Returns
the address of the current light to render, NULL if the parsing is over.
-
virtual const RED::Object *GetGeometryDatabase() const = 0
The returned object implements the RED::IGeometryDatabase interface. Note that when accessed from a RED::ISoftRayContext, we’re in a threaded rendering, and the RED::IGeometryDatabase should be used using RED::ISoftRayContext::GetThreadID as calling thread number.
- Returns
The geometry database containing the scene we’re rendering. Maybe returned NULL for some specific rendering workflows.
-
virtual bool IsComputingGI() const = 0
Are we in a global illumination calculation phase?
- Returns
true if the caller’s thread is actually performing a GI calculation, false otherwise.
-
virtual const RED::Object *GetCamera() const = 0
- Returns
a pointer to the camera the ray comes from (can be NULL)
-
virtual const RED::Matrix *GetMatrix() const = 0
Gets the transformation matrix of the last object hit on the ray stack. The result can be NULL if the object has no matrix.
- Returns
a pointer to the matrix (can be NULL).
-
virtual const RED::Matrix *GetInverseTransposeMatrix() const = 0
Gets the inverse transpose matrix of the last object hit on the ray stack. The result can be NULL if the object has no matrix.
- Returns
a pointer to the inverse transpose matrix (can be NULL).
-
virtual double RandF() const = 0
- Returns
A random double in [0,1).
-
virtual unsigned int RandI() const = 0
- Returns
A random unsigned integer in [0,2^32-1].
-
virtual bool IsGICache() const = 0
- Returns
true if a GI cache is available, false otherwise.
-
virtual RED_RC EstimateGI(double oGI[4], const double iPoint[3], const double iNormal[3], unsigned int iRayDepth, const RED::ISoftRenderingContext &iRenderingContext) const = 0
Estimates the GI at a given point with the given orientation.
- Parameters
oGI – reference to the returned indirect illumination (direct illumination is not included).
iPoint – point where to estimate the irradiance.
iNormal – normal at the previous point.
iRayDepth – depth of the ray.
iRenderingContext – global rendering context.
- Returns
RED_OK in case of success,
RED_ALLOC_FAILURE if an internal error has failed,
RED_FAIL otherwise.
-
virtual RED_RC EstimateCaustics(double oCaustics[4], const double iPoint[3], const double iNormal[3], const RED::ISoftRenderingContext &iRenderingContext) const = 0
Estimates the illumination due to caustics at a given point and orientation.
- Parameters
oCaustics – reference to the returned caustics color.
iPoint – point where to estimate the caustics.
iNormal – normal at the previous point.
iRenderingContext – global rendering context.
- Returns
RED_OK in case of success,
RED_ALLOC_FAILURE if an internal error has failed,
RED_FAIL otherwise.
-
virtual bool CanApproximateLighting(double oLighting[4], double oIndirectLighting[4], const double iPoint[3], const double iNormal[3], const RED::ISoftRenderingContext &iRenderingContext) const = 0
Returns true if approximated lighting can be used, false otherwise.
- Parameters
oLighting – if approximate lighting can be used, this variable stores the returned lighting approximation at the given point.
oIndirectLighting – if approximate lighting can be used, this variable stores the returned indirect lighting approximation at the given point.
iPoint – shading position.
iNormal – normal at the shading position.
iRenderingContext – reference to the current rendering context.
- Returns
true if approximated lighting can be used, false otherwise.
-
virtual void GetPixelCoordinates(double oPixel[2]) const = 0
