class RED::IGeometryDatabase
This interface gives an access to the internal REDsdk acceleration structure. More...
#include <REDIGeometryDatabase.h>Inherits: IREDObject.
Public functions:
| virtual int | GetDataStateNumber ( ) const = 0 |
| virtual void | GetDimensions ( double & oXMin, double & oXMax, double & oYMin, double & oYMax, double & oZMin, double & oZMax ) const = 0 |
| 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 |
| 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 |
| virtual RED_RC | GetPrimitiveNumber ( int & oNumber, int iTID ) const = 0 |
| virtual const RED::ShapePath & | GetShapePath ( int iTID ) const = 0 |
| virtual int | GetThreadsCount ( ) const = 0 |
| virtual RED_RC | GetWCSHit ( double oHitWCS[3], int iTID, double iHit[3] ) const = 0 |
| virtual RED_RC | GetWCSPrimitive ( double oP0[3], double oP1[3], double oP2[3], int iTID ) const = 0 |
Public static functions:
| static RED::CID | GetClassID ( ) |
Detailed description:
This interface gives an access to the internal REDsdk acceleration structure.
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:
Multi-threaded query model with the RED::IGeometryDatabase interface.
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.
Functions documentation
| public static RED::CID RED::IGeometryDatabase::GetClassID | ( | ) |
| public virtual int RED::IGeometryDatabase::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.
| public virtual void RED::IGeometryDatabase::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. |
| public virtual RED_RC RED::IGeometryDatabase::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_BAD_PARAM if iTID is invalid,
Other RED_RCs can be returned from the REDsdk software ray-tracing layer.
| public virtual bool RED::IGeometryDatabase::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 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:
| public virtual RED_RC RED::IGeometryDatabase::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:
| public virtual const RED::ShapePath & RED::IGeometryDatabase::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:
| public virtual int RED::IGeometryDatabase::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:
| public virtual RED_RC RED::IGeometryDatabase::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:
| public virtual RED_RC RED::IGeometryDatabase::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:
