IViewpointRenderList
Functions
Object * |
|
Object * |
|
int |
|
Detailed Description
-
class IViewpointRenderList : public RED::IREDObject
Prioritized list of viewpoints to render.
@related Viewpoint Render Lists, class RED::IWindow, class RED::IViewpoint, Anchoring Viewpoints in a Window
Viewpoint render lists are created and managed by windows. See the RED::IWindow::CreateVRL, RED::IWindow::DeleteVRL or RED::IWindow::GetDefaultVRL calls to get access to a VRL.
A VRL store several lists of viewpoints, that are all rendered to an offscreen buffer, composed of one or many color buffers and of a depth buffer. A stencil buffer is available on the default VRL of a window, but stencil buffers are currently not available to auxiliary VRLs, due to many hardware restrictions and driver errors that arise when trying to enable OpenGL Framebuffer Objects with stencil buffers, unless the RED::OPTIONS_FORCE_STENCIL is turned on.
A given viewpoint can be shared among different VRLs. On destruction, a VRL will delete all cameras that are inserted into it and that are not shared by other VRLs that are not destroyed. This mechanism is similar to the shape tree destruction mechanism. Please refer to the \ref bk_ba_life_cycle_of_redsdk_objects paragraph for details on the object life cycle management inside REDsdk.
The format of the VRL rendering buffer is specified at the VRL creation time. Most common usage for offscreen render targets is to perform render to texture workflows: the contents of the VRL’s viewpoints are drawn in the VRL’s buffer and the results is retrieved through a render image using the built-in VRL render images (RED::IViewpointRenderList::GetRenderImage and RED::IViewpointRenderList::GetRenderDepthImage) or using manually defined render images (RED::IImage2D::SetRenderImage).
A VRL may render simultaneously to several color buffers (using OpenGL FrameBuffer Objects multiple render targets) in hardware or hybrid mode, but only using hardware rendering. The number of color buffers is specified at the creation of the VRL (see RED::IWindow::CreateVRL). Color buffers are retrieved thanks to RED::IViewpointRenderList::GetRenderImage, in specifying the number of the buffer to be retrieved.
A VRL using multiple render targets (MRT) do not support anti-aliasing methods. Similarly, hardware tonemapping set on rendered viewpoints in a VRL using MRTs will be ignored.
The lists of viewpoints in a VRL are split in 3 parts, each corresponding to a precise rendering need: foreground, scene and background part of the data to be drawn. The rendering workflow performs the following tasks:
Clear color buffer,
Clear stencil buffer,
Clear z-buffer,
Render background viewpoints in last to first order,
Clear z-buffer,
Clear stencil buffer,
Render scene viewpoints in last to first order,
Clear z-buffer,
Clear stencil buffer,
Render front viewpoints in last to first order.
This way, each list of viewpoints works in a separate z-space that does not interfere with the others. Practically, any object in a background viewpoint will appear behind all the others in the scene or front viewpoints. Each viewpoint in a given list shares the same z-space and is rendered separately in last to first order.
So, for instance, a light source in one viewpoint won’t lit an object in another viewpoint. Furthermore, ray-tracing occurs on a per viewpoint basis: each viewpoint works on its own, even if two viewpoints may see part of the same shape graph.
A VRL may be disabled. A disabled VRL is not rendered, and does not consume any rendering time. The default render images of this VRL are not updated and can be accessed. Custom render images are not updated either. However, if a viewpoint in a VRL uses a ray-tracer, the acceleration structure of that ray-tracer is kept uptodate. See the RED::IViewpointRenderList::Activate method for details.
The VRL offers access to a variety of other services, among which we find aliasing controls, the management of background images, access to hardware OpenGL informations or the setup of software ray-tracer callbacks.
The VRL offers different anti-aliasing services:
Hardware based anti-aliasing using RED::IViewpointRenderList::SetEngineAntiAlias. Engine anti-aliasing with super-scaling option enabled is the fastest and highest quality anti-aliasing option available in REDsdk. Turning on super-scaling causes more video memory to be used for the rendering.
Software based anti-aliasing using RED::IViewpointRenderList::SetSoftAntiAlias. This is for software processed images, using RED::IWindow::FrameTracing. Note that it’s generally pointless to use both anti-aliasings at the same time unless the VRL contains both hardware and software rendered viewpoints in a hybrid rendering configuration.
Note that hardware anti-aliasing is not accessible for auxiliary VRLs. Only the default VRL of a window may enable hardware anti-aliasing, through the RED::WindowRenderInfo parameter of the RED::Factory::CreateREDWindow, and the set value can be accessed using RED::IViewpointRenderList::GetHardwareAntiAlias.
Please also note that engine anti-aliasing with super-scaling renders at a far better quality than hardware anti-aliasing does, at similar speeds and similar video memory consumption.
Public Functions
-
virtual RED_RC GetSize(int &oWidth, int &oHeight, int iStateNumber = -1) const = 0
Gets the size of the VRL.
This method returns the VRL dimensions for the provided iStateNumber value.
- Parameters
oWidth – VRL render target pixel width.
oHeight – VRL render target pixel height.
iStateNumber – The queried state number.
- Returns
RED_OK when all information could be accessed,
RED_FAIL if no corresponding state exists.
-
virtual RED_RC SetSize(int iWidth, int iHeight, const RED::State &iState) = 0
Resizes a VRL.
A call to this method defines a new size for the VRL. All viewpoints in the VRL are updated to match the new overall dimensions of the VRL.
- Parameters
iWidth – Pixel width of the VRL.
iHeight – Pixel height of the VRL.
iState – Current transaction parameter.
- Returns
RED_OK in case of a successful resize,
RED_BAD_PARAM if the method received an invalid parameter,
RED_WORKFLOW_ERROR if the transaction parameter was invalid,
RED_FAIL otherwise.
-
virtual RED_RC GetPixelFormat(RED::FORMAT &oFormat, int iNumColorBuffer, int iStateNumber = -1) const = 0
Gets the pixel format of the VRL for a given color buffer number.
- Parameters
oFormat – The VRL pixel format.
iNumColorBuffer – The number of the color buffer being queried.
iStateNumber – The queried state number.
- Returns
RED_OK if the method succeeded,
RED_BAD_PARAM if iNumColorBuffer is not in bounds of the number of color buffers available,
RED_FAIL if no corresponding state exists.
-
virtual RED_RC SetPixelFormat(int iNumColorBuffer, RED::FORMAT iFormat, const RED::State &iState) = 0
Changes the pixel format of the VRL for a given color buffer number.
- Parameters
iNumColorBuffer – The number of the color buffer being targeted by the call.
iFormat – The new pixel format of the VRL.
iState – Current transaction parameter.
- Returns
RED_OK in case of success,
RED_BAD_PARAM if iNumColorBuffer is not in bounds of the number of color buffers available,
RED_WORKFLOW_ERROR if the transaction parameter was invalid,
RED_FAIL otherwise.
-
virtual RED_RC GetHardwareAntiAlias(int &oMultiSamples, int iStateNumber = -1) const = 0
Returns the hardware anti-aliasing setting for this buffer.
This method returns an effective value only for the default VRL of a window. Auxiliary VRLs of a window don’t use hardware anti-aliasing.
- Parameters
oMultiSamples – The VRL hardware anti-aliasing value. 1 indicates no hardware anti-aliasing.
iStateNumber – The queried state number.
- Returns
RED_OK when all information could be accessed,
RED_FAIL if no corresponding state exists.
-
virtual RED_RC GetEngineAntiAlias(int &oMultiSamples, bool &oSuperScale, int iStateNumber = -1) const = 0
Returns the engine anti-aliasing setting for this buffer.
Returned values are in [1-5] for x1, x4, x9, x16, x25.
- Parameters
oMultiSamples – The VRL engine anti-aliasing value.
oSuperScale – The engine anti-aliasing super scaling setup value.
iStateNumber – The queried state number.
- Returns
RED_OK when all information could be accessed,
RED_FAIL if no corresponding state exists.
-
virtual RED_RC SetEngineAntiAlias(int iMultiSamples, bool iSuperScale, const RED::State &iState) = 0
Sets the engine anti-aliasing value for the VRL.
The engine anti-aliasing is used during hardware rendering of a scene. It should not be used for software rendering passes, whose anti-aliasing is set using RED::IViewpointRenderList::SetSoftAntiAlias.
Engine anti-aliasing works by rendering the scene at a greater resolution than the VRL resolution and then by shrinking the results back to the VRL resolution. There are two methods to perform this scaled rendering:
If iSuperScale is off, the scene is rendered using tiles. For a iMultiSamples value of 3, the scene is rendered 9 times at the VRL resolution, generating a x3 wide and x3 high image which is shrinked back into the VRL rendering buffer.
If iSuperScale is on, the scene is rendered once into a x3 wide and x3 high image which is shrinked back into the VRL rendering buffer.
If iSuperScale is ‘false’, the rendering takes longer but no extra memory is consumed. If iSuperScale is ‘true’, the rendering is done once, so the performance hit is minimal (only extra pixel fill rate) but the amount of memory used for the rendering is higher, due to the allocation of an extra large internal buffer.
See more details here: \ref bk_ba_engine_anti_aliasing.
Engine anti-aliasing does not work with VRLs setup to use multiple render targets. Activating the engine anti-aliasing will cause stencil buffer to be lost, unless the RED::OPTIONS_FORCE_STENCIL is set on the corresponding window that owns the VRL.
- Parameters
iMultiSamples – The new VRL engine anti-aliasing value in [ 1, 5 ] standing for x1, x4, x9, x16 and x25.
iSuperScale – Set to ‘true’ to enable super-scaling, or ‘false’ to use the tile based engine anti-aliasing.
iState – Current transaction parameter.
- Returns
RED_OK in case of success,
RED_BAD_PARAM if the method received an invalid parameter,
RED_WORKFLOW_ERROR if the transaction parameter was invalid,
RED_WORKFLOW_ERROR if the VRL uses multiple rendering targets,
RED_FAIL otherwise.
-
virtual RED_RC GetSoftAntiAlias(unsigned int &oAASamplesRate, int iStateNumber = -1) const = 0
Returns the soft tracer anti-aliasing settings for the VRL.
- Parameters
oAASamplesRate – The VRL soft tracer anti-aliasing samples rate in [1-1000]. The real number of anti-aliasing samples per pixel is oAASamplesRate x oAASamplesRate.
iStateNumber – The queried state number.
- Returns
RED_OK when all information could be accessed,
RED_FAIL if no corresponding state exists.
-
virtual RED_RC SetSoftAntiAlias(unsigned int iAASamplesRate, const RED::State &iState) = 0
Sets the soft tracer anti-aliasing value for the VRL.
- Parameters
iAASamplesRate – The VRL soft tracer anti-aliasing samples rate in [1-1000]. The real number of anti-aliasing samples per pixel is iAASamplesRate x iAASamplesRate.
iState – Current transaction parameter.
- Returns
RED_OK in case of success,
RED_BAD_PARAM if the method received an invalid parameter,
RED_WORKFLOW_ERROR if the transaction parameter was invalid,
RED_FAIL otherwise.
-
virtual RED_RC GetClearColor(RED::Color &oColor, int iStateNumber = -1) const = 0
Returns the VRL clear color.
- Parameters
oColor – The VRL clear color.
iStateNumber – The queried state number.
- Returns
RED_OK when all information could be accessed,
RED_FAIL if no corresponding state exists.
-
virtual RED_RC SetClearColor(const RED::Color &iColor, const RED::State &iState) = 0
Sets the VRL clear color.
- Parameters
iColor – The new VRL clearance color.
iState – Current transaction parameter.
- Returns
RED_OK in case of success,
RED_BAD_PARAM if the method received an invalid parameter,
RED_WORKFLOW_ERROR if the transaction parameter was invalid,
RED_FAIL otherwise.
-
virtual RED_RC GetClearDepth(float &oDepth, int iStateNumber = -1) const = 0
Returns the VRL clear depth.
- Parameters
oDepth – The VRL clear depth.
iStateNumber – The queried state number.
- Returns
RED_OK when all information could be accessed,
RED_FAIL if no corresponding state exists.
-
virtual RED_RC SetClearDepth(float iDepth, const RED::State &iState) = 0
Sets the VRL clear depth.
- Parameters
iDepth – The new VRL clearance depth.
iState – Current transaction parameter.
- Returns
RED_OK in case of success,
RED_BAD_PARAM if the method received an invalid parameter,
RED_WORKFLOW_ERROR if the transaction parameter was invalid,
RED_FAIL otherwise.
-
virtual RED_RC GetBackgroundDepth(float &oDepth, int iStateNumber = -1) const = 0
Gets the background rendering depth.
This is the zbuffer value which is written into the rendering buffer when a background image is rendered in the VRL’s buffer. This value is slightly below the default clear depth.
- Parameters
oDepth – The VRL background image rendering depth.
iStateNumber – The queried state number.
- Returns
RED_OK when all information could be accessed,
RED_FAIL if no corresponding state exists.
-
virtual RED_RC GetBackgroundCubeImage(RED::Object *&oImage, int iStateNumber = -1) const = 0
Gets the current viewport cube background image.
- Parameters
oImage – The current cube background image. NULL if no image was set.
iStateNumber – The queried state number.
- Returns
RED_OK when all information could be accessed,
RED_FAIL if no corresponding state exists.
-
virtual RED_RC GetBackgroundCubeImageMatrix(RED::Matrix &oMatrix, int iStateNumber = -1) const = 0
Returns the transformation matrix of the background cube image.
- Parameters
oMatrix – The matrix that was specified by RED::IViewpointRenderList::SetBackgroundImages.
iStateNumber – The queried state number.
- Returns
RED_OK when all information could be accessed,
RED_FAIL if no corresponding state exists.
-
virtual RED_RC GetBackground2DImage(RED::Object *&oImage, int iStateNumber = -1) const = 0
Gets the current viewport 2D background image.
- Parameters
oImage – The current 2D background image. NULL if no image was set.
iStateNumber – The queried state number.
- Returns
RED_OK when all information could be accessed,
RED_FAIL if no corresponding state exists.
-
virtual RED_RC GetBackground2DImageMatrix(RED::Matrix &oMatrix, int iStateNumber = -1) const = 0
Returns the transformation matrix of the background 2D image.
- Parameters
oMatrix – The matrix that was specified by RED::IViewpointRenderList::SetBackgroundImages.
iStateNumber – The queried state number.
- Returns
RED_OK when all information could be accessed,
RED_FAIL if no corresponding state exists.
-
virtual RED_RC GetBackgroundImagesDirectVisibility(bool &oVisibility, int iStateNumber = -1) const = 0
Returns the visibility status of background images.
- Parameters
oVisibility – The visibility flag value as specified by RED::IViewpointRenderList::SetBackgroundImages.
iStateNumber – The queried state number.
- Returns
RED_OK when all information could be accessed,
RED_FAIL if no corresponding state exists.
-
virtual RED_RC GetBackgroundImagesIntensityScale(double &oScaleCube, double &oScale2D, int iStateNumber = -1) const = 0
Returns the intensity scale of background images.
- Parameters
oScaleCube – The scaling factor for the cube image as specified by RED::IViewpointRenderList::SetBackgroundImages.
oScale2D – The scaling factor for the 2D image as specified by RED::IViewpointRenderList::SetBackgroundImages.
iStateNumber – The queried state number.
- Returns
RED_OK when all information could be accessed,
RED_FAIL if no corresponding state exists.
-
virtual RED_RC SetBackgroundImages(RED::Object *iCubeImage, const RED::Matrix &iCubeMatrix, RED::Object *i2DImage, const RED::Matrix &i2DMatrix, bool iDirectVisibility, double iIntensityScaleCube, double iIntensityScale2D, const RED::State &iState) = 0
Defines viewport background images.
This method defines two background images that replace the default background clear color of the VRL for all fragments that don’t hit any object.
iCubeImage is a background image that is sampled using the rendered camera viewing direction, both in hardware and software rendering modes, for all rendering depths.
i2DImage is a background image that is sampled using the current viewport screen coordinates in hardware and in software for the first rendering depth (direct rays, including through transparency layers). It’s ignored for all other ray depths. Setting i2DImage overrides iCubeImage for all direct rays.
The image below illustrates the different usages of the background images:
Background images are not visible directly unless the iDirectVisibility flag is set.
i2DImage must use the RED::TGT_TEX_RECT target. It can be a 2D image or a composite image that uses the fragment position for its shading.
iCubeImage must be a RED::IImageCube image or a composite image.
Extra transformation matrices can be specified. For the cube image, this transform is applied as a rotation matrix to the ray direction to let the caller control the orientation of the background. For a 2D image, this transformation matrix is applied as a transform matrix for the fragment position. For a 2D composite image, in software, the shader decides on using the matrix or not; In hardware, the matrix is applied as a transformation matrix to the input fragment position.
Calling this method may create material in the resource manager. The ID of these created materials is set to the strings defined by RED_VRL_BACKGROUND_2D_MATERIAL and RED_VRL_BACKGROUND_CUBE_MATERIAL.
To remove background images, call SetBackgroundImages with NULL images addresses.
- Parameters
iCubeImage – The cube background image to use. This image must be a valid cube or composite image, or it can be set to NULL if no cube background is to be used.
iCubeMatrix – Incoming ray transformation matrix.
i2DImage – The 2D background image to use. This image must be a valid 2D or composite image. When set, it overrides iCubeImage for all direct rays / fragments being rendered.
i2DMatrix – Incoming window coordinate transformation matrix.
iDirectVisibility – If true, background images will be visible directly, otherwise only the cube image will be visible through ray-traced reflections and refractions.
iIntensityScaleCube – Intensity scaling factor that will be applied to the cube background image, so that the intensity of the image can easily be lowered or increased. Must be > 0.0.
iIntensityScale2D – Intensity scaling factor that will be applied to the 2D background image, so that the intensity of the image can easily be lowered or increased. Must be > 0.0.
iState – Current transaction parameter.
- Returns
RED_OK if the method has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_WORKFLOW_ERROR if the transaction parameter was invalid,
RED_FAIL otherwise.
-
virtual RED_RC GetViewpointGICaches(RED::Vector<RED::Object*> &oGICaches, RED::Object *iViewpoint, int iStateNumber = -1) const = 0
Retrieves the addresses of the camera GI caches.
Return the addresses of the current GI caches to use for the rendering of iCamera.
- Parameters
oGICaches – Addresses of the GI caches if any have been set.
iViewpoint – The viewpoint to render with an irradiance cache.
iStateNumber – The queried state number.
- Returns
RED_OK when all information could be accessed,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL if no corresponding state exists.
-
virtual RED_RC SetViewpointGICaches(const RED::Vector<RED::Object*> &iGICaches, RED::Object *iViewpoint, const RED::State &iState) = 0
Setups GI caches for the rendering of a camera.
GI cache(s) can be specified for the rendering of a camera. In that case, no GI is computed for the given camera and the provided caches are used instead.
If several caches are provided (i.e more than one), the GI information is interpolated from them. It is useful when rendering animations to reduce the GI flickering from frame to frame. The more the number of caches, the smoother the GI (too many caches may introduce light leaks).
The GI caches vector can be either empty or must contain an odd number of entries (the entry in the middle of the vector being the GI cache at the time of the current frame; caches before this entry are past caches while caches after this entry are future caches).
See the method to generate GI caches at RED::IWindow::FrameTracingGICache.
- Parameters
iGICaches – Vector of irradiance cache addresses to use for this camera. This parameter can be an empty vector to reset the irradiance caches for this camera.
iViewpoint – The viewpoint to render with the irradiance caches.
iState – Current transaction parameter.
- Returns
RED_OK if the method has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter or the number of GI caches is not 0 nor an odd number,
RED_WORKFLOW_ERROR if the transaction parameter was invalid,
RED_FAIL otherwise.
-
virtual RED_RC SetViewpointGICache(RED::Object *iGICache, RED::Object *iViewpoint, const RED::State &iState) = 0
Setups a GI cache for the rendering of a camera.
This is a helper method which is equivalent to RED::IViewpointRenderList::SetViewpointGICaches with only one cache being set.
- Parameters
iGICache – Pointer to the GI cache to use for the provided camera, or NULL to remove a previously set cache.
iViewpoint – The viewpoint to render with the irradiance caches.
iState – Current transaction parameter.
- Returns
RED_OK if the method has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_WORKFLOW_ERROR if the transaction parameter was invalid,
RED_FAIL otherwise.
-
virtual RED_RC GetViewpointSoftImages(RED::Object *&oColor, RED::Object *&oDepth, RED::Object *iViewpoint, int iStateNumber = -1) const = 0
Returns soft images currently set for this viewpoint.
Return addresses of images set by RED::IViewpointRenderList::SetViewpointSoftImages or internal images used by REDsdk for the processing of iViewpoint.
Images returned by this method are owned by REDsdk and will be destroyed by it, unless the rendering was performed using RED::IWindow::FrameTracingImages or RED::IWindow::FrameTracingImageLayers or if a call to RED::IViewpointRenderList::SetViewpointSoftImages was made.
- Parameters
oColor – Color image pointer.
oDepth – Depth image pointer.
iViewpoint – The viewpoint whose images are to be retrieved.
iStateNumber – Current transaction number.
- Returns
RED_OK if the method has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIl otherwise.
-
virtual RED_RC SetViewpointSoftImages(RED::Object *iColor, RED::Object *iDepth, RED::Object *iViewpoint, const RED::State &iState) = 0
Setups images rendered using RED::IWindow::FrameTracingImages.
Images that have been rendered and retrieved using RED::IWindow::FrameTracingImages or RED::IWindow::FrameTracingImageLayers can later be interactively post-processed by the user without the need to render them again.
By calling this method for the corresponding viewpoint, one can modify the viewpoint post processing settings in real-time and display the result using RED::IWindow::FrameDrawing. The viewpoint post processing settings can be set using RED::IViewpoint::GetPostProcessSettings.
If the supplied images were created by the caller, it is its responsibility to release them when they are no more needed. The depth image and the color image must be both valid or NULL.
If both images are NULL, the software images are removed from the processing.
- Parameters
iColor – Pointer to the color image.
iDepth – Pointer to the depth image.
iViewpoint – The viewpoint to render the post processes.
iState – Current transaction parameter.
- Returns
RED_OK if the method has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter or if one of the two images was NULL,
RED_WORKFLOW_ERROR if the transaction parameter was invalid,
RED_FAIL otherwise.
-
virtual RED_RC GetViewpointSoftMatrix(RED::Matrix *&oMatrix, RED::Object *iViewpoint, int iStateNumber = -1) const = 0
Returns soft matrix currently set for this viewpoint.
Return the matrix set by RED::IViewpointRenderList::SetViewpointSoftImages.
- Parameters
oMatrix – Pointer to the soft camera matrix.
iViewpoint – The viewpoint whose matrix are to be retrieved.
iStateNumber – Current transaction number.
- Returns
RED_OK if the method has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIl otherwise.
-
virtual RED_RC SetViewpointSoftMatrix(RED::Matrix *iMatrix, RED::Object *iViewpoint, const RED::State &iState) = 0
Setups viewpoint matrix used to get the depth image.
Images that have been rendered and retrieved using RED::IWindow::FrameTracingImages or RED::IWindow::FrameTracingImageLayers can later be interactively post-processed by the user without the need to render them again.
By calling RED::IViewpointRenderList::SetViewpointSoftImages method for the corresponding viewpoint, one can modify the viewpoint post processing settings in real-time and display the result using RED::IWindow::FrameDrawing. The viewpoint post processing settings can be set using RED::IViewpoint::GetPostProcessSettings.
In addition to RED::IViewpointRenderList::SetViewpointSoftImages, it is necessary to call this function to give the camera matrix used to get the soft images. Some post process effects need the matrix to behave properly. The soft matrix is the inverse of the projection-viewport matrix. It can be obtain with RED::IViewpointRenderList::GetInverseProjectionViewportMatrix.
If iMatrix is NULL, the soft matrix is removed from the processing.
- Parameters
iMatrix – Pointer to the camera matrix.
iViewpoint – The viewpoint to render the post processes.
iState – Current transaction parameter.
- Returns
RED_OK if the method has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter or if one of the two images was NULL,
RED_WORKFLOW_ERROR if the transaction parameter was invalid,
RED_FAIL otherwise.
-
virtual RED_RC GetViewpointSoftPixelAnalysisCallback(RED::SOFT_PIXEL_ANALYSIS_CALLBACK &oCallback, void *&oUserData, bool &oTwoSided, RED::Object *iViewpoint, int iStateNumber = -1) const = 0
Returns the pixel analysis callback for this viewpoint.
- Parameters
oCallback – Address of the callback method for iViewpoint.
oUserData – User data for the callback method.
oTwoSided – Single side or two side analysis.
iViewpoint – The viewpoint whose callback is queried.
iStateNumber – Current transaction number.
- Returns
RED_OK if the method has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL otherwise.
-
virtual RED_RC SetViewpointSoftPixelAnalysisCallback(RED::SOFT_PIXEL_ANALYSIS_CALLBACK iCallback, void *iUserData, bool iTwoSided, RED::Object *iViewpoint, const RED::State &iState) = 0
Sets a callback to analyze a pixel in software ray-tracing.
This method sets a callback to be used with iViewpoint. The callback is called once for every pixel in the image that has a visible primitive in it. To get this result, pixel beams are fired by the software ray-tracer through each screen pixel, and the method is called for each hit geometrical primitive.
This method is analytical. The anti-aliasing setting has no effect on it as it propagates a pixel pyramidal beam that cover the pixel beam volume, as illustrated by the image below:
The shape of the propagated pixel beam depends on the type of the camera. In the image illustration above, the camera is a RED::VPT_PERSPECTIVE camera. For each kind of camera, the geometrical shape of the beam is adjusted to cover the volume visualized by a pixel.
Note that when a pixel analysis callback is set on a viewpoint, no output image will be returned by RED::IWindow::FrameTracing for this viewpoint.
Please also note that the Embree acceleration structure does not support pixel analysis. Consequently, RED::OPTIONS_RAY_USE_EMBREE should be disabled before using pixel analytics.
- Parameters
iCallback – The callback method address. The address can be NULL to remove the callback.
iUserData – User data parameters sent to the callback.
iTwoSided – Single side or two side analysis. If this flag is set to true, both front and back facing hit triangles will be returned. Otherwise, this is the material of the hit shape that rules the front or back side consideration.
iViewpoint – The camera whose image will be processed with the callback.
iState – Current transaction parameter.
- Returns
RED_OK if the method has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL otherwise.
-
virtual RED_RC GetViewpointSoftBucketCallback(RED::SOFT_BUCKET_CALLBACK &oCallback, void *&oUserData, RED::Object *iViewpoint, int iStateNumber = -1) const = 0
Retrieves the current soft bucket callback parameters.
- Parameters
oCallback – The user callback.
oUserData – User data pointer for the callback.
iViewpoint – The ray-traced camera.
iStateNumber – The current transaction number.
- Returns
RED_OK if the method has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL otherwise.
-
virtual RED_RC SetViewpointSoftBucketCallback(RED::SOFT_BUCKET_CALLBACK iCallback, void *iUserData, RED::Object *iViewpoint, const RED::State &iState) = 0
Sets a custom bucket feeding callback for the software ray-tracer for this viewpoint.
- Parameters
iCallback – The user callback.
iUserData – User data pointer for the callback.
iViewpoint – The ray-traced camera.
iState – Current transaction.
- Returns
RED_OK if the method has succeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetViewpointSoftTileOffset(int &oOffsetX, int &oOffsetY, RED::Object *iViewpoint, int iStateNumber = -1) const = 0
Gets the viewpoint soft tile offset.
- Parameters
oOffsetX – Offset of the tile along the x-axis.
oOffsetY – Offset of the tile along the y-axis.
iViewpoint – The ray-traced camera.
iStateNumber – The current transaction number.
- Returns
RED_OK if the method has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL otherwise.
-
virtual RED_RC SetViewpointSoftTileOffset(RED::Object *iViewpoint, int iOffsetX, int iOffsetY, const RED::State &iState) = 0
Sets the offset in (x,y) of the tile being visualised.
When rendering with tiles, viewpoints are dynamically setup to focus only on a sub-part of a bigger image.
In the context of the tile, pixels are rendered in the [0,0] x [tile width,tile height] range, whereas in fact they are offseted from the tile offsets in the bigger image.
This method lets the user set what is the offset of the tile in the whole image. This is mandatory if you want your image being the same as if it was rendered at-once, using no tiling (this is because of the random number generators being initialised using the pixel coordinates as seed).
- Parameters
iViewpoint – The ray-traced camera.
iOffsetX – offset of the tile along the x-axis.
iOffsetY – offset of the tile along the y-axis.
iState – Current transaction.
- Returns
RED_OK if the method has succeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetViewpointSoftClipBox(double &oBXMin, double &oBXMax, double &oBYMin, double &oBYMax, double &oBZMin, double &oBZMax, RED::Matrix &oMatrix, RED::Object *iViewpoint, int iStateNumber = -1) const = 0
Retrieves the actual clip box of the software rendering.
Retrieves the software ray-tracer clip box actually set for the model. By default, the box being set has infinite boundaries: [ -DBL_MAX, DBL_MAX ] x [ -DBL_MAX, DBL_MAX ] x [ -DBL_MAX, DBL_MAX ].
- Parameters
oBXMin – Box boundaries.
oBXMax – Box boundaries.
oBYMin – Box boundaries.
oBYMax – Box boundaries.
oBZMin – Box boundaries.
oBZMax – Box boundaries.
oMatrix – Matrix transformation of the box.
iViewpoint – The ray-traced camera.
iStateNumber – The current transaction number.
- Returns
RED_OK if the method has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL otherwise.
-
virtual RED_RC SetViewpointSoftClipBox(double iBXMin, double iBXMax, double iBYMin, double iBYMax, double iBZMin, double iBZMax, const RED::Matrix &iMatrix, RED::Object *iViewpoint, const RED::State &iState) = 0
Defines a clipping box for a software rendering.
This method can be used to clip the entire rendering of a model in software. All rays being processed are clipped in world space coordinates to the region defined by the box below: a geometry will be visible only if it’s in [ iBXMin, iBXMax ] x [ iBYMin, iBYMax ] x [ iBZMin, iBZMax ], after the application of the matrix transformation defined by iMatrix.
- Parameters
iBXMin – Box boundaries.
iBXMax – Box boundaries.
iBYMin – Box boundaries.
iBYMax – Box boundaries.
iBZMin – Box boundaries.
iBZMax – Box boundaries.
iMatrix – Extra transformation of the software clip box.
iViewpoint – The ray-traced camera.
iState – Current transaction parameter.
- Returns
RED_OK if the method has succeded,
RED_BAD_PARAM if the method has received invalid box coordinates,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC ResetViewpointSoftClipBox(RED::Object *iViewpoint, const RED::State &iState) = 0
Resets any previously set viewpoint software clip box.
This method resets any viewpoint soft clip box previously set by RED::IViewpointRenderList::SetViewpointSoftClipBox.
- Parameters
iViewpoint – The ray-traced camera.
iState – Current transaction parameter.
- Returns
RED_OK if the method has succeded,
RED_BAD_PARAM if the method has received invalid box coordinates,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetViewpointSoftRayProcessingCallbacks(RED::SOFT_RAY_PROCESSING_INTERSECTION_CALLBACK &oIntersectCallback, RED::SOFT_RAY_PROCESSING_SHADING_CALLBACK &oShadingCallback, void *&oUserData, RED::Object *iViewpoint, int iStateNumber) = 0
Retrieves the custom software ray-tracing callbacks.
- Parameters
oIntersectCallback – The user intersection callback.
oShadingCallback – The user shading callback.
oUserData – User data pointer for the callbacks.
iViewpoint – The ray-traced camera.
iStateNumber – The current transaction number.
- Returns
RED_OK if the method has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL otherwise.
-
virtual RED_RC SetViewpointSoftRayProcessingCallbacks(RED::SOFT_RAY_PROCESSING_INTERSECTION_CALLBACK iIntersectCallback, RED::SOFT_RAY_PROCESSING_SHADING_CALLBACK iShadingCallback, void *iUserData, RED::Object *iViewpoint, const RED::State &iState) = 0
Setups custom software ray-tracing callbacks.
This method can be used to modify the behavior of the software ray-tracer, by specifying a custom intersection method and a custom shading method.
The intersection callback is launched for each ray processed by the software ray-tracer. It can be used to add external intersections to the regular process. For instance, custom analytical objects, defined at the user application level can be handled by the intersection callback, in addition to the objects stored in the scene graph and handled by the software ray-tracer.
For each intersection returned by the intersection callback, the shading callback will be called to gather the needed shading parameters to have the custom intersection processed by the engine.
Both callbacks must be valid or NULL to remove the custom ray processing.
Note that these callbacks are ignored by the processing of pixel analytics.
- Parameters
iIntersectCallback – The user custom intersection callback.
iShadingCallback – The user custom shading callback.
iUserData – The user data pointer to send to the callbacks.
iViewpoint – The ray-traced camera.
iState – The current transaction parameter.
- Returns
RED_OK if the method has succeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetViewpointGeometryDatabase(RED::Object *&oGeometryDatabase, RED::Object *iViewpoint, int iStateNumber = -1) const = 0
Retrieves the ray-tracer acceleration structure for a given viewpoint.
This method retrieves the geometry database (e.g. the ray-tracer acceleration structure) stored by the VRL for the specified iViewpoint. The oGeometryDatabase object returned exists only if iViewpoint has been rendered with ray-tracing options being enabled (recall that setting up RED::OPTIONS_RAY_PRIMARY is enough to activate any ray-tracer). Otherwise, the returned object is NULL. REDsdk must have been initialized using software rendering (hybrid of full software for this method to work).
The retrieved oGeometryDatabase implements the RED::IGeometryDatabase interface. Please refer to the interface documentation for all details.
- Parameters
oGeometryDatabase – The retrieved acceleration structure if it exists, NULL otherwise.
iViewpoint – The ray-traced camera.
iStateNumber – The accessed transaction number.
- Returns
RED_OK if the method has succeeded,
RED_WORKFLOW_ERROR if REDsdk is running in hardware only mode. Software rendering is required to access the geometry database,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL otherwise.
-
virtual RED_RC GetViewpoint(RED::Object *&oVP, int iNumber, RED::VRL_SORT iListID, int iStateNumber = -1) const = 0
Gets a viewpoint by its number in a list.
- Parameters
oVP – The returned viewpoint. NULL in case of error.
iNumber – The number of the viewpoint in the list.
iListID – The list to lookup for the viewpoint.
iStateNumber – The queried state number.
- Returns
RED_OK when the access succeeded,
RED_BAD_PARAM if the method received an invalid parameter.
-
virtual RED_RC GetViewpointList(RED::Vector<RED::Object*> *&oVP, RED::VRL_SORT iListId, int iStateNumber = -1) const = 0
Gets a list of viewpoints in the VRL.
- Parameters
oVP – The requested list of viewpoints. NULL in case of error.
iListId – The identifier of the list to return.
iStateNumber – The queried state number.
- Returns
RED_OK when the operation succeeded,
RED_BAD_PARAM if the method received an invalid parameter.
-
virtual RED_RC GetViewpointsCount(int &oCount, int iStateNumber = -1) const = 0
Gets the total number of viewpoints in the VRL.
- Parameters
oCount – Number of viewpoints in the VRL. This sums the back, scene and front viewpoints. 0 in case of error.
iStateNumber – The queried state number.
- Returns
RED_OK when the operation succeeded,
RED_BAD_PARAM if the method received an invalid parameter.
-
virtual RED_RC GetViewpoint(RED::Object *&oVp, int iNumber, int iStateNumber = -1) const = 0
Gets viewpoint by its global number.
Access the viewpoint based on its number in the whole set of viewpoints of the VRL. Back, scene and front lists of viewpoints are considered as a single list in which iNumber is the index in the complete list.
- Parameters
oVp – Returned viewpoint. NULL in case of error.
iNumber – Number of the accessed viewpoint.
iStateNumber – The queried state number.
- Returns
RED_OK when the operation succeeded,
RED_BAD_PARAM if the method received an invalid parameter.
-
virtual RED_RC GetViewpointSortList(RED::VRL_SORT &oList, int iNumber, int iStateNumber = -1) const = 0
Gets the list for a given viewpoint’s index.
Returns the list (RED::VRL_SORT) to which the viewpoint at global index iNumber belong. The global viewpoint list considers back, then scene then front viewpoints.
- Parameters
oList – List to which the viewpoint belongs.
iNumber – Number of the accessed viewpoint.
iStateNumber – The queried state number.
- Returns
RED_OK when the operation succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
-
virtual RED_RC FindViewpoint(bool &oFound, RED::Object *iViewpoint, int iStateNumber = -1) const = 0
Is a viewpoint in our VRL?
This method parses the three viewpoint lists of this VRL to look for iViewpoint.
- Parameters
oFound – true if iViewpoint exists in our VRL, false otherwise.
iViewpoint – Viewpoint address to look for.
iStateNumber – Current transaction parameter.
- Returns
RED_OK when the operation succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
-
virtual RED_RC GetViewpointBoundaries(const RED::Object *iViewpoint, int &oXAnchor, int &oYAnchor, int &oXSize, int &oYSize, int iStateNumber = -1) const = 0
Gets viewpoint anchor and dimenstions.
This method access the viewpoint boundaries information: It’s anchoring position and it’s dimensions.
oXSize and oYSize are the viewpoint width and height in screen pixels, drawn at the oXAnchor and oYAnchor position. The (0,0) point is at the bottom left corner of the screen. Note that viewpoint pixel dimensions may be negative. This simulates a moving anchor position. For example, to anchor the top-right corner of the viewpoint, width and height sizes of the viewpoint are negative.
- Parameters
iViewpoint – Viewpoint whose dimensions are to be accessed.
oXAnchor – X coordinates of the viewpoint anchor position.
oYAnchor – Y coordinates of the viewpoint anchor position.
oXSize – Width of the viewpoint (may be negative).
oYSize – Height of the viewpoint (may be negative).
iStateNumber – Queried state number
- Returns
RED_OK when the information could be accessed,
RED_BAD_PARAM if an invalid parameter was provided to the routine,
RED_FAIL if no corresponding state exists.
-
virtual RED_RC GetViewpointSizingModes(RED::Object *iViewpoint, int &oAnchoringMode, int &oSizingMode, int iStateNumber = -1) const = 0
Gets anchoring and sizing mode for the viewpoint.
This method returns iViewpoint’s anchoring mode and sizing mode, as they were specified either during its insertion.
- Parameters
iViewpoint – Viewpoint’s whose parameters are to be accessed.
oAnchoringMode – One of RED::VSP_ANCHOR_FIXED or RED::VSP_ANCHOR_STRETCHED, specifying a fixed attach point or a moving one along with window size changes.
oSizingMode – One of RED::VSP_SIZE_FIXED, RED::VSP_SIZE_STRETCHED or RED::VSP_SIZE_STRETCHED_AUTO_RATIO.
iStateNumber – Queried state number.
- Returns
RED_OK when the information could be accessed,
RED_BAD_PARAM if an invalid parameter was provided to the routine,
RED_FAIL if no corresponding state exists.
-
virtual RED_RC InsertViewpoint(RED::Object *iViewpoint, RED::VRL_SORT iFrontSceneOrBack, RED::LIST_POS iFirstOrLastInList, int iXAnchor, int iYAnchor, int iXSize, int iYSize, float iXAsymmetricOffset, float iYAsymmetricOffset, RED::VRL_SIZEPOS iAnchoringMode, RED::VRL_SIZEPOS iSizingMode, const RED::State &iState) = 0
Viewpoint VRL addition method.
This method inserts the provided iViewpoint in the VRL’s list. The boundaries of the viewpoint in the VRL can be specified using this method.
iXSize and iYSize are the viewpoint width and height in screen pixels, drawn at the iXAnchor and iYAnchor position. The ( 0, 0 ) point is at the bottom left corner of the screen.
Note that viewpoint pixel dimensions may be negative. This simulates a moving anchor position. For example, to anchor the top-right corner of the viewpoint, use negative width and height viewpoint sizes.
A viewpoint may be asymmetric if needed (for the purpose of tiling for example). Setting iXAsymmetricOffset or iYAsymmetricOffset to a non zero number of pixels, translates the center of the view (e.g. what’s in front of the sight vector) of a given number of pixels. Positive x heads right, and positive y heads top. Note that non integer pixels may be provided, in case of half pixels offsets or other fractions are needed.
Using asymmetry offsets does not change where the image is being drawn in the window: This is defined by the anchor and the size associated to the viewpoint; This changes the way the frustum is generated. To perform screen tiling, with 100 640x480 viewpoints for example, declare a window of 6400x4800 pixels, then declare viewpoints of 640x480 pixels in the window, each at it’s tiled position, and use asymmetric offsets to properly replace the center of each viewpoint’s rendering area. Note that calculations with asymmetric viewpoints differ from normal viewpoints. The RED::IViewpoint interface offer all queries and access method to properly handle asymmetries.
A viewpoint that is inserted with a RED::VSP_SIZE_STRETCHED sizing mode has its frustum ratio forced to match the height / width ratio of its rendering area in the VRL. This ensures that upon a resize operation, the resulting rendering of the viewpoint does not get stretched by a viewport ratio change.
- Parameters
iViewpoint – The camera object to insert. Duplicate insertion of the same viewpoint will provoke a RED_BAD_PARAM.
iFrontSceneOrBack – Set to RED::VST_FRONT, RED::VST_SCENE or to RED::VST_BACK, indicates which list in the VRL the viewpoint is to be added in.
iFirstOrLastInList – Inside each list, viewpoint rendering order may be meaningful. This flag can be set to RED::LIST_FIRST or to RED::LIST_LAST. Viewpoints are rendered last to first in a list.
iXAnchor – Viewpoint anchoring position X coordinate. The anchoring position may be negative.
iYAnchor – Viewpoint anchoring position Y coordinate. The anchoring position may be negative.
iXSize – Pixel width of the viewpoint. Note that this parameter may be negative. In this case, the viewpoint is drawn to the left of the anchor position.
iYSize – Pixel height of the viewpoint. Note that this parameter may be negative. In this case, the viewpoint is drawn to the bottom of the anchor position.
iXAsymmetricOffset – Number of pixels to offset the center of the image from the viewport area along the right axis.
iYAsymmetricOffset – Number of pixels to offset the center of the image from the viewport area along the top axis.
iAnchoringMode – One of RED::VSP_ANCHOR_FIXED or RED::VSP_ANCHOR_STRETCHED, specifying a fixed attach point or a moving one along with window size changes.
iSizingMode – One of RED::VSP_SIZE_FIXED, RED::VSP_SIZE_STRETCHED or RED::VSP_SIZE_STRETCHED_AUTO_RATIO specifying a fixed viewpoint size or a moving viewpoint size. Note that a stretched auto ratio viewpoint has its ratio updated to match the viewport’s one.
iState – The current transaction parameter.
- Returns
RED_OK when the insertion succeeded,
RED_BAD_PARAM if an invalid parameter was provided to the method,
RED_BAD_PARAM if iViewpoint is already inserted in the VRL,
RED_WORKFLOW_ERROR if the transaction parameter was invalid,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
-
virtual RED_RC InsertViewpoint(RED::Object *iViewpoint, RED::VRL_SORT iFrontSceneOrBack, int iPosition, int iXAnchor, int iYAnchor, int iXSize, int iYSize, float iXAsymmetricOffset, float iYAsymmetricOffset, RED::VRL_SIZEPOS iAnchoringMode, RED::VRL_SIZEPOS iSizingMode, const RED::State &iState) = 0
Insert a viewpoint in a VRL at a fixed position in a list of viewpoints.
See RED::IViewpointRenderList::InsertViewpoint for details.
- Parameters
iViewpoint – The camera object to insert.
iFrontSceneOrBack – Set to RED::VST_FRONT, RED::VST_SCENE or to RED::VST_BACK, indicates which list in the VRL the viewpoint is to be added in.
Position – in the specified list. If the position is negative, the insertion is first in list. If the position is above the number of viewpoints in the list, the insertion is last in list. Otherwise, it’s at the specified value.
iXAnchor – Viewpoint anchoring position X coordinate. The anchoring position may be negative.
iYAnchor – Viewpoint anchoring position Y coordinate. The anchoring position may be negative.
iXSize – Pixel width of the viewpoint. Note that this parameter may be negative. In this case, the viewpoint is drawn to the left of the anchor position.
iYSize – Pixel height of the viewpoint. Note that this parameter may be negative. In this case, the viewpoint is drawn to the bottom of the anchor position.
iXAsymmetricOffset – Number of pixels to offset the center of the image from the viewport area along the right axis.
iYAsymmetricOffset – Number of pixels to offset the center of the image from the viewport area along the top axis.
iAnchoringMode – One of RED::VSP_ANCHOR_FIXED or RED::VSP_ANCHOR_STRETCHED, specifying a fixed attach point or a moving one along with window size changes.
iSizingMode – One of RED::VSP_SIZE_FIXED, RED::VSP_SIZE_STRETCHED or RED::VSP_SIZE_STRETCHED_AUTO_RATIO specifying a fixed viewpoint size or a moving viewpoint size. Note that a stretched auto ratio viewpoint has its ratio updated to match the viewport’s one.
iState – The current transaction parameter.
- Returns
RED_OK when the insertion succeeded,
RED_BAD_PARAM if an invalid parameter was provided to the method,
RED_BAD_PARAM if iViewpoint is already inserted in the VRL,
RED_WORKFLOW_ERROR if the transaction parameter was invalid,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
-
virtual RED_RC InsertViewpoint(RED::Object *iViewpoint, const RED::State &iState) = 0
Viewpoint VRL addition method.
This method is a simple helper for basic viewpoint insertions. It does exactly:
RED_RC rc; int width, height; RED::IViewpointRenderList* ivrl = ...; rc = ivrl->GetSize( width, height ); rc = ivrl->InsertViewpoint( iViewpoint, RED::VST_SCENE, RED::LIST_FIRST, 0, 0, width, height, 0.0f, 0.0f, RED::VSP_ANCHOR_STRETCHED, RED::VSP_SIZE_STRETCHED_AUTO_RATIO, iState );
The viewpoint is inserted first in the RED::VST_SCENE list of the VRL. This helper works as the RED::IWindow::InsertViewpoint helper for the viewpoint insertion in the default VRL.
- Parameters
iViewpoint – The viewpoint to add to the VRL.
iState – The current transaction.
- Returns
RED_OK when the insertion succeeded,
RED_BAD_PARAM if an invalid parameter was provided to the method,
RED_BAD_PARAM if iViewpoint is already inserted in the VRL,
RED_WORKFLOW_ERROR if the transaction parameter was invalid,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
-
virtual RED_RC RemoveViewpoint(RED::Object *iViewpoint, const RED::State &iState) = 0
Removes the viewpoint identified by iViewpoint in the VRL.
This method looks for iViewpoint in the list and removes all found instances of it. iViewpoint is not deleted.
Inserting a viewpoint in a VRL may be a time consuming task if the viewpoint is tied to a large scene that needs to be initialized at the first time it is viewed. So, once this cost has been paid (often at the time the window pops on screen, or at application startup), its better not to remove the viewpoint until the scene is to be discarded. When the camera needs to be modified, prefer to manually update the viewpoint parameters instead of replacing it with another one if the two are visualizing the same scene.
- Parameters
iViewpoint – The viewpoint address to look for in the list.
iState – Current transaction parameter.
- Returns
RED_OK when the insertion succeeded,
RED_BAD_PARAM if an invalid parameter was provided,
RED_WORKFLOW_ERROR if the transaction parameter was invalid,
RED_ALLOC_FAILURE if an internal allocation did fail,
RED_FAIL otherwise.
-
virtual RED_RC RemoveViewpointList(RED::VRL_SORT iList, const RED::State &iState) = 0
Removes all viewpoints in one list of the VRL.
This method removes all viewpoints in one of the RED::VRL_SORT lists of the VRL. No viewpoints are deleted by the method.
- Parameters
iList – The list to clear.
iState – The current transaction parameter.
- Returns
RED_OK when the insertion succeeded,
RED_BAD_PARAM if an invalid parameter was provided,
RED_WORKFLOW_ERROR if the transaction parameter was invalid,
RED_ALLOC_FAILURE if an internal allocation did fail,
RED_FAIL otherwise.
-
virtual RED_RC SetViewpointBoundaries(RED::Object *iViewpoint, int iXAnchor, int iYAnchor, int iXSize, int iYSize, int iAnchoringMode, int iSizingMode, const RED::State &iState) = 0
Changes viewpoint’s anchoring position and rendering size.
This method changes the viewpoints anchoring position, anchoring mode and rendering dimensions in the VRL’s render target.
- Parameters
iViewpoint – The viewpoint to be modified in the VRL.
iXAnchor – Viewpoint anchoring position X coordinate. This value can be negative.
iYAnchor – Viewpoint anchoring position Y coordinate. This value can be negative.
iXSize – Pixel width of the viewpoint. Note that this parameter may be negative. In this case, the viewpoint is drawn to the left of the anchor position.
iYSize – Pixel height of the viewpoint. Note that this parameter may be negative. In this case, the viewpoint is drawn to the bottom of the anchor position.
iAnchoringMode – Value must be one of RED::VSP_ANCHOR_FIXED or RED::VSP_ANCHOR_STRETCHED, specifying a fixed attach point or a moving one along with window size changes. If 0, the anchoring mode of the viewpoint is not modified.
iSizingMode – Value must be one of RED::VSP_SIZE_FIXED, RED::VSP_SIZE_STRETCHED or RED::VSP_SIZE_STRETCHED_AUTO_RATIO, specifying a fixed viewpoint size or a moving viewpoint size changing with the vrl size. If 0, the sizing mode of the viewpoint is not modified.
iState – Current transaction parameter.
- Returns
RED_OK if the viewpoint boundaries could be changed,
RED_BAD_PARAM if an invalid parameter was provided to the routine,
RED_WORKFLOW_ERROR if the transaction parameter was invalid,
RED_FAIL otherwise.
-
virtual RED::Object *GetRenderImage(int iColorBufferNumber = 0) const = 0
Gets a built-in color buffer render image of the VRL contents.
This method retrieves a render image of the VRL color buffer. It’s filled with the result of the VRL rendering. Using this image is fast and does not consume any extra memory, unlike using RED::IImage2D::SetRenderImage.
The render image retrieved through this method should not be used by a shader involved in the rendering of the VRL itself, otherwise, the results will be undefined (this creates a rendering loop, where the image contents will be overwritten during the rendering at the same time it gets used for the rendering).
The built-in render image of the VRL uses the RED::TGT_TEX_RECT target, has the format of the VRL and has the dimensions of the VRL. It’s automatically resized with the VRL.
The default VRL of a window has no built-in images. If called, the method will return NULL. To create a render image on the default VRL of a window, please apply RED::IImage2D::SetRenderImage on any image created using the resource manager (see RED::IResourceManager::CreateImage2D).
The built-in color buffer render image of a VRL don’t appear in RED::IResourceManager::GetImageList.
A first rendering with that VRL activated must have occurred before the texture is set with valid contents. However, the image address can be accessed right after the VRL construction.
Before the first time this VRL is rendered, the retrieved image can’t be modified (or changes will have no effect). After this first time draw, it’s possible to change the filter modes, wrap modes, border color and anisotropy setting of the image.
- Parameters
iColorBufferNumber – Number of the targeted color buffer. By default, the method returns the first and unique color buffer of the VRL. More color buffers may be handled by the VRL, as defined during its creation using RED::IWindow::CreateVRL.
- Returns
The VRL color buffer render image address. The default VRL of a window has no built-in render color image and the method will return NULL for it.
-
virtual RED::Object *GetRenderDepthImage() const = 0
Gets a built-in depth buffer render image of the VRL contents.
The method behaves identically to RED::IViewpointRenderList::GetRenderImage, except that it returns a depth buffer image instead of a color buffer image.
- Returns
The VRL depth buffer render image address. The default VRL of a window has no built-in render depth image and the method will return NULL for it.
-
virtual int GetRenderImagesCount() const = 0
Retrieves the number of render images handled by this VRL.
The method returns the number of render color images declared at the VRL creation using RED::IWindow::CreateVRL. By default, a VRL renders to a single offscreen color buffer / image.
- Returns
The number of built-in render images accessible for this VRL.
-
virtual RED_RC GetViewpointAsymmetricOffsets(RED::Object *iViewpoint, float &oXAsymmetricOffset, float &oYAsymmetricOffset, int iStateNumber = -1) const = 0
Gets the asymmetric offsets for a viewpoint.
A standard viewpoint drawing results are centered with it’s drawing boundaries, meaning that objects in front of the viewpoint (intersected by it’s sight vector) appears in the center of its rendering area.
Asymmetric offsets translates the result of the drawn viewpoint of a given number of pixels, changing the viewpoint’s perspective or parallel frustum.
This method retrieves the offset values in use for the provided iViewpoint object address.- Parameters
iViewpoint – Viewpoint’s offsets being accessed.
oXAsymmetricOffset – Pixel offset along the viewpoint’s right vector to apply during the viewport transformation.
oYAsymmetricOffset – Pixel offset along the viewpoint’s top vector to apply during the viewport transformation.
iStateNumber – Queried state number.
- Returns
RED_OK when the information could be accessed,
RED_BAD_PARAM if an invalid parameter was provided to the routine,
RED_FAIL if no corresponding state exists.
-
virtual RED_RC SetViewpointAsymmetricOffsets(RED::Object *iViewpoint, float iXAsymmetricOffset, float iYAsymmetricOffset, const RED::State &iState) = 0
Sets viewpoint frustum pixel offsets.
This method sets the offsets that translates the center of the viewing frustum for the rendering, making it asymmetric.
The provided offsets are expressed in pixels, and only interferes with the definition of the frustum for the rendering of the viewpoint’s contents. No other parameters are being modified. The viewpoint remains at the same position in the window, with the same rendering bounds.
When non zero offsets are set, the viewpoint is turned into an asymmetric viewpoint, recomputing the appropriate focal to correctly render the view.
Setting back offsets to zero turn back the viewpoint to a symmetrical one if it were asymmetric.
Note that this method does not work with viewpoints that are using a custom projection matrix.- Parameters
iViewpoint – Viewpoint’s offsets being accessed.
iXAsymmetricOffset – Pixel offset along the viewpoint’s right vector to apply during the viewport transformation.
iYAsymmetricOffset – Pixel offset along the viewpoint’s top vector to apply during the viewport transformation.
iState – Current transaction parameter.
- Returns
RED_OK when the information could be accessed,
RED_BAD_PARAM if an invalid parameter was provided to the routine,
RED_WORKFLOW_ERROR if the transaction parameter was invalid,
RED_FAIL otherwise.
-
virtual RED_RC Activate(bool iOnOff, const RED::State &iState) = 0
Enables or disables the VRL’s rendering.
By default, a VRL is activated at its creation time. Desactivating the default VRL of a window cancels the window buffer swapping operation.
Desactivating a VRL will preserve any software ray-tracer acceleration structure accociated to viewpoints with ray-tracing options being enabled. Refer to RED::IWindow::FrameTracing for further details.
- Parameters
iOnOff – Set to true to activate the VRL for the rendering or false to inactivate the VRL and prevent it from being rendered anymore.
iState – Current transaction parameter.
- Returns
RED_OK when the operation has succeeded,
RED_ALLOC_FAILURE if an internal memory allocation has failed,
RED_WORKFLOW_ERROR if the transaction parameter was invalid,
RED_FAIL otherwise.
-
virtual RED_RC IsActivated(bool &oOnOff, int iStateNumber = -1) const = 0
Gets the current activation status for the VRL.
- Parameters
oOnOff – Returned set to true if the VRL is active or set to false if the VRL is currently inactive.
iStateNumber – Queried state number.
- Returns
RED_OK when the information could be accessed,
RED_BAD_PARAM if an invalid parameter was provided to the routine,
RED_FAIL otherwise.
-
virtual RED_RC SetMustClear(bool iClear, const RED::State &iState) = 0
Enables or disables rendering buffer clear.
It’s not possible to use the engine anti-aliasing in a buffer whose clear is disabled. This results in an incorrectly rendered image.
- Parameters
iClear – Set this flag to true to force the VRL buffer clear at rendering startup (default), or set it to draw in a buffer that is not cleared.
iState – Current transaction parameter.
- Returns
RED_OK when the operation has succeeded,
RED_ALLOC_FAILURE if an internal memory allocation has failed,
RED_WORKFLOW_ERROR if the transaction parameter was invalid,
RED_FAIL otherwise.
-
virtual RED_RC MustClear(bool &oMustClear, int iStateNumber = -1) const = 0
Does the VRL needs to clear its buffer?
- Parameters
oMustClear – Returned set to true if the VRLs has to clear its 3D rendering buffer, or set to false otherwise.
iStateNumber – Queried state number.
- Returns
RED_OK when the information could be accessed,
RED_BAD_PARAM if an invalid parameter was provided to the routine,
RED_FAIL otherwise.
-
virtual RED_RC SetHDROverride(bool iOverride, int iHDRValue, const RED::State &iState) = 0
Overrides the HDR option for this specific VRL.
This method can be used to bypass the HDR option that is defined at the window level. Practically, the HDR can be enabled for all VRLs in a given window using RED::OPTIONS_WINDOW_HDR
or it can be setup at the VRL level using this method.
By default, a VRL does not override the window option value.
- Parameters
iOverride – Do this VRL override the HDR option ?
iHDRValue – HDR option value. in [0,2]. See RED::OPTIONS_WINDOW_HDR.
iState – Current transaction parameter.
- Returns
RED_OK when the operation has succeeded,
RED_ALLOC_FAILURE if an internal memory allocation has failed,
RED_WORKFLOW_ERROR if the transaction parameter was invalid,
RED_FAIL otherwise.
-
virtual RED_RC GetHDROverride(bool &oOverride, int &oHDRValue, int iStateNumber = -1) const = 0
Retrieves HDR override parameters for this VRL.
Returns the HDR setup sent through the SetHDROverride method. The default behavior of a VRL is not to override the window option values.
- Parameters
oOverride – Do this VRL override the HDR option ?
oHDRValue – HDR option value. in [0,2]. See RED::OPTIONS_WINDOW_HDR.
iStateNumber – Queried state number.
- Returns
RED_OK when the information could be accessed,
RED_BAD_PARAM if an invalid parameter was provided to the routine,
RED_FAIL otherwise.
-
virtual RED_RC SetStereo(float iInteraxialDistance, float iScreenDepth, const RED::State &iState) = 0
Specifies stereoscopic parameters for all cameras in this VRL.
Stereo display is enabled at the window level during it’s creation using the RED::WindowRenderInfo parameters. Then, this method sets the stereo parameters that are needed to setup all perspective cameras in this VRL so that they produce a stereo result.
Please refer to the \ref bk_ba_stereoscopy chapter in the REDsdk programming guide for all details on the stereoscopy setup.
- Parameters
iInteraxialDistance – This is the distance between the two eyes.
iScreenDepth – This is the convergence plane distance. Objects that are beyond this plane will appear “inside” the screen and objects that are in front of this plane will appear “outside” the screen, popping in front of the viewer.
iState – Current transaction parameter.
- Returns
RED_OK when the operation has succeeded,
RED_ALLOC_FAILURE if an internal memory allocation has failed,
RED_WORKFLOW_ERROR if the transaction parameter was invalid,
RED_FAIL otherwise.
-
virtual RED_RC GetStereo(float &oInteraxialDistance, float &oScreenDepth, int iStateNumber = -1) const = 0
Retrieves stereoscopic parameters for this VRL.
If the VRL is not rendering stereoscopic data, then it’s interaxial distance and screen depth are both 0.0.
- Parameters
oInteraxialDistance – Distance between the two eyes.
oScreenDepth – Convergence plane distance.
iStateNumber – Queried state number.
- Returns
RED_OK when the information could be accessed,
RED_BAD_PARAM if an invalid parameter was provided to the routine,
RED_FAIL otherwise.
-
virtual RED_RC GetViewportMatrix(RED::Matrix &oViewport, RED::Object *iCamera, int iStateNumber = -1) const = 0
Calculates and returns the viewport matrix of a camera in the VRL.
The method calculates the viewport matrix of the specified iCamera in the VRL. The viewport matrix transform a point in normalized device coordinates into a point in screen coordinates for display.
For all details on the REDsdk transformation pipeline, please refer to \ref bk_ba_matrix_transforms_in_a_cluster.
- Parameters
oViewport – The calculated viewport matrix.
iCamera – The camera whose viewport matris is to be calculated.
iStateNumber – The transaction number for the query.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_BAD_PARAM if iCamera was not found,
RED_FAIL otherwise.
-
virtual RED_RC GetViewProjectionViewportMatrix(RED::Matrix &oVPV, const RED::Object *iCamera, int iStateNumber = -1) const = 0
Calculates and returns the VPV matrix of a camera.
This method calculates and return the view-projection-viewport matrix of the specified iViewpoint rendered in the context of this viewport VRL. The view-projection-viewport (VPV) matrix is the cumulated product of the camera viewport matrix by the camera view-projection matrix.
For all details on the REDsdk transformation pipeline, please refer to \ref bk_ba_matrix_transforms_in_a_cluster.
- Parameters
oVPV – The calculated view-projection-viewport matrix.
iCamera – The camera whose VPV matrix is to be calculated.
iStateNumber – The transaction number for the query.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_BAD_PARAM if iCamera was not found,
RED_FAIL otherwise.
-
virtual RED_RC GetFloatingViewProjectionViewportMatrix(RED::Matrix &oVPV, const RED::Object *iCamera, int iStateNumber = -1) const = 0
Calculates and returns the VPV matrix of a camera with floating origin applied.
This is the ( viewport ) x ( projection ) x ( ( floating origin x view ) invert ) matrix.
The floating origin of the camera is defined using RED::IViewpoint::SetFloatingOrigin. For all details on the REDsdk transformation pipeline, please refer to \ref bk_ba_matrix_transforms_in_a_cluster.
- Parameters
oVPV – The calculated floating view-projection-viewport matrix.
iCamera – The camera whose floating VPV matrix is to be calculated.
iStateNumber – The transaction number for the query.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_BAD_PARAM if iCamera was not found,
RED_FAIL otherwise.
-
virtual RED_RC GetInverseProjectionViewportMatrix(RED::Matrix &oIPV, const RED::Object *iCamera, int iStateNumber = -1) const = 0
Calculates and returns the inverse of the projection-viewport matrix.
This method calculates and return the inverse of the projection-viewport matrix of the specified iViewpoint rendered in the context of this viewport VRL. The projection-viewport (PV) matrix is the cumulated product of the camera viewport matrix by the camera projection matrix.
For all details on the REDsdk transformation pipeline, please refer to \ref bk_ba_matrix_transforms_in_a_cluster.
This matrix can be used to convert from depth buffer unit to camera unit.
- Parameters
oIPV – The calculated inverse projection-viewport matrix.
iCamera – The camera whose inverse PV matrix is to be calculated.
iStateNumber – The transaction number for the query.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_BAD_PARAM if iCamera was not found,
RED_FAIL otherwise.
