IGeometryDatabase
Functions
int |
|
void |
|
int |
|
bool |
|
const ShapePath & |
|
Detailed Description
-
class IGeometryDatabase : public RED::IREDObject
This interface gives an access to the internal REDsdk acceleration structure.
@related Tracing Custom Rays
The RED::IGeometryDatabase interface is a direct access to the internal REDsdk acceleration structure that is created by REDsdk while rendering an image. This interface to the acceleration structure can be used to do spatial queries on the data contained in a scene or cast rays into it.
Using the database can’t be performed anytime. The database contents are defined by the last transaction that has been rendered. By rendered, is meant that a call to RED::IWindow::FrameDrawing or RED::IWindow::FrameTracing (any FrameTracing call) has been performed.
All changes done in the current transaction are unknown to the database. The database only contains data that has been specified during a transaction that has been closed and rendered.
For performance reasons, the geometry database queries are not mutex-locked in multi-threaded environments. Consequently it’s the responsibility of the caller to ensure that its calls are made at the right time:
The database is synchronized on the transaction number indicated by RED::IGeometryDatabase::GetDataStateNumber. If database queries are to be performed while the engine is drawing, on another thread, the caller must check that the value returned by RED::IGeometryDatabase::GetDataStateNumber fits its requirements. If the value returned is not equal to the rendered transaction number, then this indicates that the engine has not updated the database yet and therefore it should not be used yet. This is indicated by the “database update” box in the picture above.
Similarly, the caller must ensure that another FrameDrawing / FrameTracing call has not started while it’s still doing parallel queries on the database. As soon as a rendering is started, the database may be invalidated or modified during the update. Parallel queries in this period may be fatal to the application, or at best can return wrong results.
Access to the RED::IGeometryDatabase class is performed by camera on the RED::IViewpointRenderList class, Each camera rendered in the context of a window may store a geometry database. The database associated to a camera in a given VRL and window can be accessed using RED::IViewpointRenderList::GetViewpointGeometryDatabase.
Public Functions
-
virtual int GetDataStateNumber() const = 0
Gets the transaction number for which the database contents exists.
This method returns the transaction number for which the geometry database has been updated. As detailed in the class header documentation, in multi-threaded environments, there’s a period of time during which the geometry database gets updated and can’t be asked for anything.
-
virtual void GetDimensions(double &oXMin, double &oXMax, double &oYMin, double &oYMax, double &oZMin, double &oZMax) const = 0
Returns the database dimensions.
These boundaries enclose all geometries visualized in the scene.
- Parameters
oXMin – Database bounds coordinate.
oXMax – Database bounds coordinate.
oYMin – Database bounds coordinate.
oYMax – Database bounds coordinate.
oZMin – Database bounds coordinate.
oZMax – Database bounds coordinate.
-
virtual int GetThreadsCount() const = 0
Returns the number of threads declared for using this geometry database.
This method returns the number of threads that were declared at the initialization of this geometry database acceleration structure. The number of threads is based on the number of available physical cores and on the RED::OPTIONS_RAY_MAX_THREADS option value.
- Returns
The number of threads usable for querying this database.
-
virtual bool GetIntersection(int &oTID, double oHit[3], const double iE[3], const double iP[3], int iTIDSource, int iTIDDestination, double iTMin, bool iForceTwoSided, bool iPrimary, int iThreadNumber = -1) const = 0
Retrieves the closest triangle intersection along a ray.
This method throws a ray inside the geometry database and retrieve the closest intersected primitive from the ray starting point iE. The intersection process can ignore a startup triangle iTIDSource and also it can ignore a destination triangle iTIDDestination. This can avoid bad self intersections that could occur otherwise while processing rays starting or ending on a known surface.
The ray propagation can be clamped from the starting position iE using the iTMin startup parametric length of the intersection along the ray.
The propagated ray can be considered as a primary ray if iPrimary is true. In this case, objects that were discarded by the means of the visibility callbacks won’t appear in the results.
The propagation of the ray may also consider all geometries inside the database as being double sided if iForceTwoSided is true.
This method can be used from a multi-threaded environment if iThreadNumber is specified. Note that all REDsdk internal calculations (from RED::IWindow::FrameTracing and derived methods) must have been stopped before calling GetIntersection with a iThreadNumber. If this rule is not enforced, the engine may crash.
However, you can still call the interface methods in a multi-threaded environment during rendering if it happens from within a shader and uses the shader thread number: see \ref wf_tracing_custom_rays for a complete sample of custom ray checks during rendering.
- Parameters
oTID – The identifier of the intersected triangle. Refer to the decoding methods of the geometry database to retrieve informations associated to this triangle.
oHit – Hit information (t,u,v): Parametric value along the ray at the intersection and interpolation UVs at the intersection on the hit triangle.
iE – Ray starting position.
iP – Ray ending position.
iTIDSource – Source primitive ID to skip for ray take-off. Set to zero to ignore this parameter.
iTIDDestination – Destination primitive ID to skip for ray landing. Set to zero to ignore this parameter.
iTMin – Minimal parametric value along the ray above which we can consider a primitive for intersection, to force forward moves.
iForceTwoSided – Set to true to force all intersections to be two sided.
iPrimary – Set to true if we’re a primary ray.
iThreadNumber – Optional parameter that can be used to specify the calling thread number. By default, this parameter is -1, indicating a single thread usage of the RED::IGeometryDatabase. Multi-threaded GetIntersection queries can be performed by specifying a iThreadNumber >= 0. In this case, iThreadNumber must be lower than the number of threads that was declared for using the geometry database. See RED::IGeometryDatabase::GetThreadsCount. Also, all REDsdk internal calculations must have been stopped before using this method in a multi-threaded environment.
- Returns
true if an intersection has been found, false otherwise.
-
virtual RED_RC GetWCSHit(double oHitWCS[3], int iTID, double iHit[3]) const = 0
Retrieves an intersection point after a ray propagation.
Return the point hit by a ray in the primitive identified by iTID, whose parametric hit informations are stored in iHit. These two parameters are resulting of RED::IGeometryDatabase::GetWCSHit.
- Parameters
oHitWCS – Coordinate of the hit point, in WCS.
iTID – The identifier of the hit primitive.
iHit – Hit information (t,u,v): Parametric value along the ray at the intersection and interpolation UVs at the intersection on the hit primitive.
- Returns
RED_OK if the method has succeeded,
RED_BAD_PARAM if iTID is invalid.
-
virtual RED_RC GetWCSPrimitive(double oP0[3], double oP1[3], double oP2[3], int iTID) const = 0
Retrieves a primitive’s definition vertices from a iTID.
According to the type of the primitive (point, line, triangle, text), some of the returned points may be filled with valid data or not. For a point, only oP0 is filled; for a line oP0 and oP1 are both filled; and for triangles and texts, all three points oP0, oP1 and oP2 are valid.
The returned primitive is in world space coordinates.
- Parameters
oP0 – First primitive vertex, in WCS.
oP1 – Second primitive vertex, in WCS.
oP2 – Third triangle vertex, in WCS.
iTID – Identifier of the primitive.
- Returns
RED_OK if the method has succeeded,
RED_BAD_PARAM if iTID is invalid.
-
virtual RED_RC GetPrimitiveNumber(int &oNumber, int iTID) const = 0
Retrieve a primitive number from a iTID.
This method decodes the iTID returned by a call to RED::IGeometryDatabase::GetIntersection. It returns the number of the primitive in the source object (number of triangle for a mesh, number of segment for line,…)
- Parameters
oNumber – Number of the primitive.
iTID – Identifier of the primitive.
- Returns
RED_OK if the method has succeeded,
RED_BAD_PARAM if iTID is invalid.
-
virtual const RED::ShapePath &GetShapePath(int iTID) const = 0
Retrieves the hit primitive shape path.
This method retrieves the hit shape instance path.
- Parameters
iTID – Identifier of the primitive.
- Returns
The primitive shape path. The path is empty if iTID is invalid.
-
virtual RED_RC GetGIDiffuseColor(RED::Color &oColor, const double iE[3], const double iP[3], int iTID, const double iTHit[3], int iThreadNumber = -1) const = 0
Access the global illumination diffusion color at a hit primitive.
iE, iP, iTID and iHit are the same parameters as those in RED::IGeometryDatabase::GetIntersection. iTID and iHit are retrieved after a successful intersection.
- Parameters
oColor – The corresponding color.
iE – Ray starting position.
iP – Ray ending position.
iTID – Identifier of the primitive.
iHit – Hit information (t,u,v): Parametric value along the ray at the intersection and interpolation UVs at the intersection on the hit triangle.
iThreadNumber – Optional parameter that can be used to specify the calling thread number. By default, this parameter is -1, indicating a single thread usage of the RED::IGeometryDatabase. Multi-threaded GetIntersection queries can be performed by specifying a iThreadNumber >= 0. In this case, iThreadNumber must be lower than the number of threads that was declared for using the geometry database. See RED::IGeometryDatabase::GetThreadsCount. Also, all REDsdk internal calculations must have been stopped before using this method in a multi-threaded environment.
- Returns
RED_OK if the method has succeeded,
RED_BAD_PARAM if iTID is invalid,
Other RED_RCs can be returned from the REDsdk software ray-tracing layer.
-
virtual int GetDataStateNumber() const = 0
