#include <RRObject.h>
Classes | |
| struct | FaceGroup |
| class | FaceGroups |
| struct | LayerParameters |
| struct | LodInfo |
Public Member Functions | |
| RRObject () | |
| virtual | ~RRObject () |
| virtual RRCollider * | getCollider () const |
| virtual void | setCollider (RRCollider *collider) |
| virtual RRMaterial * | getTriangleMaterial (unsigned t, const class RRLight *light, const RRObject *receiver) const |
| virtual void | getPointMaterial (unsigned t, RRVec2 uv, const RRColorSpace *colorSpace, bool interpolated, RRPointMaterial &out) const |
| virtual void | getTriangleLod (unsigned t, LodInfo &out) const |
| virtual void | setWorldMatrix (const RRMatrix3x4 *worldMatrix) |
| virtual const RRMatrix3x4Ex * | getWorldMatrix () const |
| const RRMatrix3x4Ex & | getWorldMatrixRef () const |
| virtual void * | getCustomData (const char *name) const |
| void | updateIlluminationEnvMapCenter () |
| RRMesh * | createWorldSpaceMesh () const |
| unsigned | checkConsistency (const char *objectNumber) const |
| RRCollisionHandler * | createCollisionHandlerFirstVisible () const |
| virtual RRHash | getHash () const |
| void | updateFaceGroupsFromTriangleMaterials () |
| virtual void | recommendLayerParameters (RRObject::LayerParameters &layerParameters) const |
 Public Member Functions inherited from rr::RRUniformlyAllocated | |
| void * | operator new (std::size_t n) |
| void * | operator new[] (std::size_t n) |
| void | operator delete (void *p, std::size_t n) |
| void | operator delete[] (void *p, std::size_t n) |
Public Attributes | |
| FaceGroups | faceGroups |
| RRObjectIllumination | illumination |
| RRString | name |
| bool | enabled |
| bool | isDynamic |
Additional Inherited Members | |
| Protected Member Functions inherited from rr::RRUniformlyAllocatedNonCopyable | |
| RRUniformlyAllocatedNonCopyable () | |
| ~RRUniformlyAllocatedNonCopyable () | |
Detailed Description
Common interface for all proprietary object formats.
Provided information
RRObject provides information about
- materials and their assignment to faces, see faceGroups
- transformation matrix, see getWorldMatrix() and setWorldMatrix()
- collider for fast ray-mesh intersections, see getCollider() and setCollider()
- indirectly also mesh (via getCollider()->getMesh())
- LODs, see getTriangleLOD()
- object illumination, see illumination
- object name, see name
Links between objects
solver and RRScene -> RRObjects -> RRObject -> RRCollider -> RRMesh
where A -> B means that
- A has pointer to B
- there is no automatic reference counting in B and no automatic destruction of B from A
This means that multiple objects may share one collider and mesh, multiple scenes or solvers may share one object etc.
Constructor & Destructor Documentation
◆ RRObject()
| rr::RRObject::RRObject | ( | ) |
◆ ~RRObject()
|
virtual |
Member Function Documentation
◆ getCollider()
|
inlinevirtual |
Returns collider of underlying mesh. It is also access to mesh itself (via getCollider()->getMesh()). Must always return valid collider, implementation is not allowed to return nullptr.
◆ setCollider()
|
virtual |
Sets collider and mesh.
By changing collider, you change also mesh and possibly number of triangles, so make sure to update also faceGroups to have the same number of triangles as mesh. Object does not adopt/delete the collider, it keeps Caller must ensure collider stays alive until object destruction or next setCollider() call.
◆ getTriangleMaterial()
|
virtual |
Returns material description for given triangle.
Default implementation is just different way to access data stored in faceGroups. However, this function may provide additional information. If you wish to disable lighting or shadowing for specific light-caster-receiver combinations, reimplement this function to return nullptr for that combination of parameters, fall back to default implementation for others combinations.
Although more precise per-pixel material query is available in getPointMaterial(), this per-triangle version is often preferred for its speed and simplicity. Returned pointer must stay valid and constant for whole life of object.
Editing materials
Caller is allowed to modify returned materials including textures (textures are owned and deleted by material, so when changing texture, old one must be deleted). Filtered objects (e.g. objects created by createMultiObject()) share materials, so by modifying base object, filtered one is modified too.
- Parameters
-
t Triangle number. light nullptr or one of lights in scene. With light==nullptr, returned material must be always the same non-nullptr. With light!=nullptr, it is allowed to return nullptr to disable lighting or shadowing, see receiver for details. receiver nullptr or one of static objects in scene. Used only when light!=nullptr, controls properties of given light. When receiver==nullptr, you may return nullptr to make triangle invisible for given light (disables both direct lighting and shadow-casting). When receiver!=nullptr, you may return nullptr to disable direct shadow casting of triangle for given light and receiver.
◆ getPointMaterial()
|
virtual |
Returns material description for point on object's surface, fills colorLinear with values read from textures.
This is higher quality but slower per-pixel version of faster per-triangle getTriangleMaterial().
Default implementation takes point details from optional textures in material returned by getTriangleMaterial().
Offline GI solver uses getPointMaterial() only if requested lightmap quality>getTriangleMaterial()->minimalQualityForPointMaterials. Realtime GI solvers never call getPointMaterial().
Thread safe: yes, offline solver calls it from many thread concurrently.
- Parameters
-
t Triangle number. uv 2D coordinates of point, in triangle's space. Triangle vertices are in 0,0 1,0 0,1. colorSpace Function reads point details from textures, converts them with colorSpace and writes result to colorLinear. interpolated Makes texture reads interpolated. out Undefined on input, function fills it with material for requested point.
◆ getTriangleLod()
|
virtual |
Returns information about single object, what LOD it is.
In Lightsprint, LODs are completely separated objects without any pointers linking them. The only information that connects them comes from this function.
Default implementation makes all objects unique, they return different bases and level 0.
- Parameters
-
t Triangle number, relevant only for multiobjects, individual triangles in multiobject may return different results. out Caller provided storage for result. For valid t, requested LOD info is written to out. For invalid t, out stays unmodified.
◆ setWorldMatrix()
|
virtual |
Sets object transformation from local to world space.
It copies data from your matrix rather than remembering your pointer. nullptr is accepted as no transformation. If you set identity matrix, getWorldMatrix() will return nullptr.
◆ getWorldMatrix()
|
virtual |
Returns object transformation from local to world space.
Returns nullptr for identity, for use in "if (matrix) slow_transform_path; else fast_identity_path;" scenarios. Transformation can be changed by setWorldMatrix().
- Returns
- Pointer to matrix that transforms object space to world space. May return nullptr for identity/no transformation. Pointer must be constant and stay valid for whole life of object. Matrix may change during object life.
◆ getWorldMatrixRef()
| const RRMatrix3x4Ex & rr::RRObject::getWorldMatrixRef | ( | ) | const |
Returns object transformation from local to world space.
◆ getCustomData()
|
virtual |
Returns arbitrary additional data provided by adapter, or nullptr for unsupported data.
- Parameters
-
name Identifier of custom data requested. It is good practise to use names that describe both type and semantic of returned data. You are free to define and support any names in your adapters. Usage example: const char* objectName = (const char*)object->getCustomData("const char* objectName");
◆ updateIlluminationEnvMapCenter()
| void rr::RRObject::updateIlluminationEnvMapCenter | ( | ) |
Updates illumination.envMapWorldCenter and illumination.envMapWorldRadius.
Relevant for realtime GI lighting only. It is called automatically from setStaticObjects() and allocateBuffersForRealtimeGI(), but you should update the values whenever you move or scale object later, otherwise object's illumination environment map used for realtime GI lighting will be inaccurate.
◆ createWorldSpaceMesh()
| RRMesh * rr::RRObject::createWorldSpaceMesh | ( | ) | const |
Creates and returns RRMesh that describes mesh after transformation to world space.
Newly created instance allocates no additional memory, but depends on original object, so it is not allowed to let new instance live longer than original object.
◆ checkConsistency()
| unsigned rr::RRObject::checkConsistency | ( | const char * | objectNumber | ) | const |
Reports inconsistencies found in object. Returns number of problem reported.
- Parameters
-
objectNumber Arbitrary string that is inserted into error messages, to identify object.
◆ createCollisionHandlerFirstVisible()
| RRCollisionHandler * rr::RRObject::createCollisionHandlerFirstVisible | ( | ) | const |
Creates and returns collision handler, that finds closest visible surface.
Finds closest surface with RRMaterial::sideBits::render and specularTransmittance.color!=1.
It is suitable e.g for picking objects in rendering window, only visible pixels collide.
Thread safe: this function yes, but created collision handler no. (typical use case: for n threads, use 1 collider, n rays and n handlers.)
◆ getHash()
|
virtual |
Returns hash of object data. Slow (not cached).
Hashing covers object properties that affect realtime global illumination: positions, normals, tangents, texcoords, material properties (even extracted from textures), transformation. Hashing doesn't cover: full texture data, names, uv indices.
◆ updateFaceGroupsFromTriangleMaterials()
| void rr::RRObject::updateFaceGroupsFromTriangleMaterials | ( | ) |
Fills faceGroups according to results provided by getTriangleMaterial().
Fills faceGroups automatically, however, you may call it only if you implemented your own RRObject with your own self-contained getTriangleMaterial() not reading data from faceGroups.
◆ recommendLayerParameters()
|
virtual |
Recommends layer parameters (resolution, filename etc).
Nearly all tools and samples need to decide what lightmap resolutions to use, what lightmap filenames to use etc. Samples are free to use arbitrary resolutions and filenames and often they do. But for convenience of undecided tools and samples, this function is provided as a central point of their decision making.
Applications often have some opinion, so this function takes their suggections on resolution, path, extension etc, stored in layerParameters (suggestedXxx fields). Recommended new resolution, filename etc are output into the same structure (actualXxx fields).
Custom implementations of this function use different decision making rules. For example adapter of Gamebryo .gsa scene never recommends vertex buffer, because Gamebryo doesn't support lighting in vertex buffers yet.
- Parameters
-
layerParameters Structure of both inputs (suggestedXxx) and outputs (actualXxx). Outputs are filled by this function.
Member Data Documentation
◆ faceGroups
| FaceGroups rr::RRObject::faceGroups |
Assignment of materials to triangles.
First facegroup describes first numTriangles in object, next facegroup next triangles etc. Results are undefined if faceGroups contains nullptr materials or fewer triangles than mesh.
◆ illumination
| RRObjectIllumination rr::RRObject::illumination |
Illumination of the object.
◆ name
| RRString rr::RRObject::name |
Optional name of the object.
◆ enabled
| bool rr::RRObject::enabled |
Disabled object becomes invisible for renderer. Not fully implemented for static objects, disabled static object might stay visible.
◆ isDynamic
| bool rr::RRObject::isDynamic |
Is this object dynamic = is it safe to modify it?
This flag does not enforce anything, you set it as you wish and you comply with it if you wish. Object does not become static by clearing this flag, it is static if you treat it as static, e.g. by passing it to setStaticObjects() and not moving it. But it's practical to have this bit of information here, it is saved to .rr3 files, scene viewer reads it from .rr3 files etc.
