IWindow
Functions
void * |
|
const WindowRenderInfo & |
|
void |
|
void |
|
const FrameStatistics & |
|
void |
|
Detailed Description
-
class IWindow : public RED::IREDObject
This interface gives access to the window’s parameters.
@related Windows, class RED::IViewpointRenderList
The window is created through RED::Factory::CreateREDWindow, and can’t be created otherwise.
Rendering is achieved with the setup of a visualization cluster that must contain the following objects:
a resource manager instance (see RED::IResourceManager and the RED::Factory class for the creation of the CID_REDResourceManager),
at least one window,
at least one viewpoint (see RED::IViewpoint and the RED::Factory class for the creation of a CID_REDViewpoint object),
a scene graph inserted in the viewpoint (see RED::IShape and all other related scene graphs interfaces, and the factory for the creation of the corresponding shape instances).
Viewpoints are grouped in “viewpoint render lists”, whose properties are accessible through the RED::IViewpointRenderList interface. They provide a way to compose a scene with multiple data sources in the same window.
Viewpoints may also be directly managed through the helper insertion method: RED::IWindow::InsertViewpoint.
Upon destruction, a window destroys all viewpoints it owns. A viewpoint unreferences itself from all other windows and VRLs that may use it. A window is destroyed by a call to RED::Factory::DeleteInstance.
\task tk_creating_a_redsdk_window_using_the_red_factory
Public Functions
-
SET_CID(CID_class_REDIWindow)
-
virtual RED_RC InsertViewpoint(RED::Object *iViewpoint, const RED::State &iState) = 0
Quick viewpoint insertion in the default VRL.
The window handles a list of viewpoint render list objects (RED::IViewpointRenderList or VRL for short). Each VRL has a given rendering target (the screen back buffer, or an auxiliary offscreen buffer).
The window always has a default VRL, whose target is the back buffer of the frame buffer.
This method is a helper that inserts the provided viewpoint in the scene viewpoint list of the default VRL. The inserted viewpoint occupies the entire window screen space, and is tied to the 4 sides of the window (and so has dimensions that always remain identical to the window’s ones). The viewpoint’s anchor and ratio are automatically stretched to match the window parameters. See the RED::IViewpointRenderList interface for details on the viewpoint insertion mechanism.
Viewpoints in a given VRL viewpoint list are rendered in last to first order.
Please refer to \ref bk_ba_viewpoint_render_lists for details.
- Parameters
iViewpoint – Viewpoint to insert in the window.
iState – Current transaction.
- Returns
RED_OK when the insertion has succeeded,
RED_BAD_PARAM if an invalid parameter was provided,
RED_BAD_PARAM if iViewpoint is already inserted in the default VRL,
RED_INIT_FAILED if the window did not properly initialize,
RED_ALLOC_FAILURE if an internal allocation did fail,
RED_FAIL otherwise.
-
virtual RED_RC GetViewpoint(RED::Object *&oViewpoint, int iViewpointNumber, int iStateNumber = -1) = 0
Quick viewpoint access helper.
Access a viewpoint by it’s number in the scene list of the default VRL of the window. This method is intended for use with RED::IWindow::InsertViewpoint, as both target the same list of viewpoints in the same VRL.
- Parameters
oViewpoint – The returned viewpoint, NULL in case of failure.
iViewpointNumber – Number of the viewpoint to access in the list.
iStateNumber – Queried state number.
- Returns
RED_OK when the method has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_INIT_FAILED if the window did not properly initialize.
-
virtual RED_RC GetViewpointsCount(int &oCount, int iStateNumber = -1) = 0
Quick viewpoint access helper.
Returns the number of viewpoints in the scene list of the default VRL.
- Parameters
oCount – The number of viewpoints in that list of the VRL.
iStateNumber – Queried state number.
- Returns
RED_OK when the method has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_INIT_FAILED if the window did not properly initialize.
-
virtual RED_RC RemoveViewpoint(RED::Object *iViewpoint, const RED::State &iState) = 0
Removes a viewpoint from the window.
This method can be used to remove a given viewpoint from the VRLs in the window. All VRLs are searched for the viewpoint to remove.
- Parameters
iViewpoint – Viewpoint to remove from the window.
iState – Current transaction.
- Returns
RED_OK when the insertion has succeeded,
RED_BAD_PARAM if an invalid parameter was provided,
RED_INIT_FAILED if the window did not properly initialize,
RED_ALLOC_FAILURE if an internal allocation did fail,
RED_FAIL otherwise.
-
virtual RED_RC GetDefaultVRL(RED::Object *&oVRL, int iStateNumber = -1) = 0
Gets the default RED::IViewpointRenderList.
This method returns the default RED::IViewpointRenderList (VRL) that is used by the window to manage viewpoints to display. This VRL always target the back buffer of the frame buffer.
- Parameters
oVRL – The address of the first VRL.
iStateNumber – Queried state number.
- Returns
RED_OK if the method has succeeded,
RED_BAD_PARAM if the method has received an invalid iStateNumber or,
RED_INIT_FAILED if the window was not properly initialized.
-
virtual RED_RC CreateVRL(RED::Object *&oVRL, int iWidth, int iHeight, RED::FORMAT iFormat, bool iZBuffered, const RED::State &iState) = 0
Creates a new viewpoint render list (VRL).
This method creates a new VRL in the window. The VRL implements the RED::IViewpointRenderList interface. The VRL is an offscreen rendering buffer used to render a sorted list of viewpoints. A VRL provides an access to render images (see RED::IViewpointRenderList::GetRenderImage) that can be used to reuse the offscreen buffer contents in another rendering pass.
- Parameters
oVRL – Created RED::IViewpointRenderList address.
iWidth – Width of the target offscreen buffer.
iHeight – Height of the target offscreen buffer.
iFormat – A GPU device supported image format. Note that the most common format is the RED::FMT_RGBA, which is available on all hardware. Then the RED::FMT_FLOAT_RGBA is available on all GPUs that are able to do floating point calculations, to run the ray-tracer and to do HDR calculations. Then other formats may be available or not depending on the underlying GPU, OS and driver combination. For example, the RED::FMT_RGB is available on NVIDIA hardware but not on legacy ATI hardware. An invalid format request will cause a RED_DRV_NO_PIXEL_FORMAT return code to be returned by the RED::IWindow::FrameDrawing call.
iZBuffered – If true, the created VRL will have a depth buffer, if false, it doesn’t have a depth storage.
iState – Current transaction.
- Returns
RED_OK when the VRL could be successfully created,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_INIT_FAILED if the window did not properly initialize,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
-
virtual RED_RC CreateMultiRenderTargetVRL(RED::Object *&oVRL, int iWidth, int iHeight, RED::FORMAT iFormat[RED_MAX_FBO_COLORS], int iColorBufferCount, bool iZBuffered, const RED::State &iState) = 0
Creates a new viewpoint render list (VRL), that renders to multiple buffers.
The method is similar to RED::IWindow::CreateVRL, except that the created VRL may target multiple rendering buffers at once when using REDsdk hardware or hybrid rendering modes. Multiple render targets is a hardware OpenGL Framebuffer Object feature supported by REDsdk, that can be enabled through this method.
- Parameters
oVRL – Created RED::IViewpointRenderList address.
iWidth – Width of the target offscreen buffer.
iHeight – Height of the target offscreen buffer.
iFormat – A GPU device supported image format specified per buffer. Note that the most common format is the RED::FMT_RGBA, which is available on all hardware. Then the RED::FMT_FLOAT_RGBA is available on all GPUs that are able to do floating point calculations, to run the ray-tracer and to do HDR calculations. Then other formats may be available or not depending on the underlying GPU, OS and driver combination. For example, the RED::FMT_RGB is available on NVIDIA hardware but not on legacy ATI hardware. An invalid format request will cause RED_DRV_NO_PIXEL_FORMAT to be returned by the RED::IWindow::FrameDrawing call.
iState – Current transaction.
iColorBufferCount – This value define the number of hardware offscreen color buffers managed by the VRL. By default, the VRL uses one color buffer plus one depth / stencil buffer. Increasing this number may be used to define more color buffers associated to the VRL that can be accessed by shader programs. Please note that this parameter is ignored in software or if the underlying hardware does allow OpenGL FrameBuffer Objects (FBOs). The number of allowed auxiliary color buffers is RED_MAX_FBO_COLORS, but less may be accepted depending on the underlying hardware capabilities.
iZBuffered – If true, the created VRL will have a depth buffer, if false, it doesn’t have a depth storage.
- Returns
RED_OK when the VRL could be successfully created,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_BAD_PARAM if iColorBufferCount is greater than 1 and the rendering hardware does not allow iColorBufferCount to be allocated,
RED_WORKFLOW_ERROR if iColorBufferCount is greater than 1 and REDsdk runs in software mode,
RED_FAIL if iColorBufferCount is greater than 1 and the hardware don’t accept OpenGL Framebuffer Objects,
RED_INIT_FAILED if the window did not properly initialize,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
-
virtual RED_RC DeleteVRL(RED::Object *iVRL, const RED::State &iState) = 0
Removes an existing VRL from the window list.
This method removes the provided iVRL from the window list. Along with the VRL’s removal, the offscreen buffer it was linked with is released. The removed VRL is deleted during this call. This deletes all viewpoints still in the VRL and that are not shared with another VRL.
Note that images that were sourcing their contents from that deleted VRL are not removed from the materials that may be using them. It’s up to the caller to do that job.
The default VRL can’t be removed.
- Parameters
iVRL – VRL to be removed from the window VRL list.
iState – Current transaction.
- Returns
RED_OK when the removal has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
-
virtual const RED::Vector<RED::Object*> &GetVRLList(int iStateNumber = -1) const = 0
Gets the list of VRLs currently in the window.
This method returns the array of VRLs that is currently under the control of this window.
- Parameters
iStateNumber – Queried state number.
- Returns
The list of VRLs in the window.
-
virtual RED_RC GetVRL(RED::Object *&oVRL, int iNumber, int iStateNumber = -1) const = 0
Gets a VRL by its number in the window’s list.
- Parameters
oVRL – The returned VRL if the request was correct, undefined otherwise.
iNumber – Number of the VRL in the list.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method received an invalid parameter.
-
virtual RED_RC GetVRLCount(int &oCount, int iStateNumber = -1) const = 0
Gets the number of VRLs currently in the window.
- Parameters
oCount – The number of VRL in the window.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded.
-
virtual RED_RC GetSize(int &oWidth, int &oHeight, int iStateNumber = -1) const = 0
Gets the window dimensions.
This method returns the dimensions of the window, in pixels. These dimensions are associated with the default VRL of the window.
- Parameters
oWidth – Window width in pixels.
oHeight – Window height in pixels.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_INIT_FAILED if the window did not properly initialize.
-
virtual RED_RC Resize(int iWidth, int iHeight, const RED::State &iState) = 0
Sets the window size - updates the default VRL size.
This method changes the window size to the given dimensions.
The resize only modifies the default window VRL. All viewpoints of the VRL are modified to follow the dimension changes, based on their own anchoring and sizing policies.
- Parameters
iWidth – New window width.
iHeight – New window height.
iState – Current transaction parameter.
- Returns
RED_OK when the resizing has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_INIT_FAILED if the window has not been initialized yet,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
-
virtual RED_RC FrameDrawing() = 0
Main GPU / hybrid rendering method.
Renders a frame for all cameras inserted in all RED::IViewpointRenderList objects existing in the window. This method is the main rendering call for all GPU based renderings. CPU images are rendered using RED::IWindow::FrameTracing and all derived methods.
This method renders the last transaction closed by RED::IResourceManager::EndState. Please note that at least one transaction must have been closed before calling this method.
- Returns
RED_OK if the rendering sequence has been successful,
RED_DRV_HOST_ERROR if we have pending OpenGL errors due to some external application code,
RED_WORKFLOW_ERROR if we have no closed transaction,
RED_WFLOW_NO_DRAW_STATE if no transaction has ever been closed before calling the method,
RED_WFLOW_NESTED_DRAW_CALL if we have a special rendering configuration with rendering calls called from inside the draw (case of a internal callback doing the refresh of a the view),
RED_ALLOC_FAILURE if an internal memory allocation has failed,
Any other existing RED_RC code may also be returned, due to the deferred nature of the REDsdk rendering pipeline.
-
virtual RED_RC FrameTracing(bool &oComplete, RED::FRAME_TRACING_FEEDBACK iMinFeedback = RED::FTF_BY_SURFACE_LEVEL_0, float iFeedbackInterval = 500.0f) = 0
Progressive software ray-tracing rendering method.
Renders a frame using progressive ray-tracing. Ray-traced cameras are processed using a progressive refinement and intermediate displays are shown at regular time intervals.
All other real-time cameras that are not using ray-tracing are rendered as well by the call, mixed with intermediate results resulting of the rendering of ray-traced cameras.
The FrameTracing method has to be called repeatedly until it has completed all progressive ray-traced cameras images.(in this case oComplete is returned as true). FrameTracing will continue a rendering that has not been completed only if the transaction to render is still the same (e.g. no other transaction has been ended between two calls to FrameTracing).
The RED::OPTIONS_RAY_ENABLE_SOFT_TRACER option has to be enabled on the cluster’s resource manager for this method to work properly. This indicates that the engine must do the necessary setup to render frames using only the CPU.
The FrameTracing call is exclusive with the RED::IWindow::FrameDrawing call, except in the context of a post-processing pipeline.
The method has two returning behaviors:
iMinFeedback is set to RED::FTF_BY_BLOCKS or RED::FTF_PATH_TRACING. In this case the method returns approximatively every iFeedbackInterval milliseconds.
iMinFeedback is set to RED::FTF_BY_SURFACE_LEVEL_0, RED::FTF_BY_BLOCKS_LEVEL_0 (or any greater level). In this case, the method returns after the specified quality level has been reached OR if the iFeedbackInterval time has been spent.
The method has then three main display modes providing different feedbacks to the host application:
iMinFeedback is set to RED::FTF_BY_BLOCKS or RED::FTF_BY_BLOCKS_LEVEL_0 (or any greater level): The returned image is showing pixel blocks, depending on the elapsed time since the calculation has started. The image below illustrates the kind of feedback provided by this mode:
iMinFeedback is set to RED::FTF_BY_SURFACE_LEVEL_0 (or any greater level): Once the wished quality level has been returned, the method tries to return as often as possible. The feedback uses an early calculation of the first ray hit surfaces with an interpolated shading, as illustrated below:
iMinFeedback is set to RED::FTF_PATH_TRACING: the returned image shows paths already computed, depending on the elapsed time since the calculation has started. The image below illustrates the kind of feedback provided by this mode:
We have four main usage scenarios then:
iMinFeedback is RED::FTF_BY_BLOCKS and iFeedbackInterval is around 1000 milliseconds or more: this is best to generate high quality images with anti-aliasing and complete ray-tracing calculations.
iMinFeedback is RED::FTF_BY_SURFACE_LEVEL_0 (RED::FTF_BY_BLOCKS_LEVEL_0) or more and iFeedbackInterval is around 500 milliseconds or less: this is best to display viewport quality images for which the shading is very simple and the aim is interactivity in a working environment, still in software. If the pixel shading cost is high (for example if ray-tracer options are enabled) then these modes may take longer to display a full painted image. On the other side, if the pixel shading cost is low, we have a more accurate image available at interactive rates.
iMinFeedback is RED::FTF_PATH_TRACING and iFeedbackInterval is around 16 ms: this is perfect to render pre-visualization pictures at interactive rates including full materials effects, lighting and global illumination (see \ref bk_re_path_tracing)
iMinFeedback is RED::FTF_PATH_TRACING and iFeedbackInterval is around 1000 ms or more: this is the correct mode to monitor high quality picture rendering with path-tracing.
Please note that on using a low iFeedbackInterval value, the FrameTracing method will return more often to the caller. Consequently, the calling thread spends less time on calculating the image, and this can consequently slow down the rendering. On the other hand, a low iFeedbackInterval value will preserve the application’s responsiveness, allowing the calling thread to return to the application event loop.
A call to FrameTracing may be used to maintain software ray-tracer acceleration structures of inactive VRLs uptodate. A VRL that is inactivated is not drawn, but all its cameras are processed and all ray-tracer acceleration structures kept updated. A call to RED::IWindow::FrameDrawing will not maintain acceleration structures uptodate. If a structure does not get updated every rendered transaction, then it’ll be re-initialized on the first FrameTracing call that occur. This can cause slight update lags on the first frame after some time of inactivation.
A viewpoint acceleration structure is used if the viewpoint is rendered in software (either the engine runs in full software mode or the viewpoint has ray-tracer options set AND the rendering method is FrameTracing). This acceleration structure will be released if a call to RED::IWindow::FrameTracingStop occurs with a global stop flag or if the RED::OPTIONS_RAY_PRIMARY is turned off for that viewpoint and the viewpoint gets rendered again using FrameTracing.
- Parameters
oComplete – Returned true if the rendering of all progressive cameras is finished.
iMinFeedback – The feedback mode chosen for the method. Choose either a RED::FTF_BY_BLOCKS mode (blocky image, better for high quality images), any RED::FTF_BY_SURFACE_LEVEL_0 or higher mode (clean surface image, better for fast viewporting feedback) or RED::FTF_PATH_TRACING for interactive rendering with global illumination.
iFeedbackInterval – Interval waited by the engine before returning an image. This value is used to limit the time spent calculating the specified iMinFeedback if a surface feedback is requested, or defines the regular image feedback if a block feedback has been requested in iMinFeedback.
- Returns
RED_OK if the method has succeeded,
RED_WFLOW_SOFT_TRACER_IS_DISABLED if the software tracer is disabled,
RED_INTERRUPT on a user interruption. A call to RED::IWindow::FrameTracingStopmust occur after an interruption to complete the frame that is interrupted, or another image can be processed.
As for
RED::IWindow::FrameDrawing, all kinds of return codes can be returned by this method for all deferred operations that are postponed until a rendering starts.
-
virtual RED_RC FrameTracingStop(bool iGlobalStop = true) = 0
Interrupts a RED::IWindow::FrameTracing call.
Stops any frame being processed by RED::IWindow::FrameTracing call for this window. All ray-tracer threads are interrupted and closed. After the return of this method, workflows that were blocked because of the FrameTracing calls are possible again (such as image operations for example).
Depending on the value of iGlobalStop, all memory used by the software ray-tracer gets released or not, for all cameras in all VRLs of the window.
- Parameters
iGlobalStop – If true, all the memory used by the software ray-tracer is released. If false, the frame is interrupted, but ray-tracer acceleration structure remain alive, and another frame can be started with no performance hit.
- Returns
RED_OK if the method has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC FrameTracingGICache(bool &oComplete, RED::Object *&oGICache, RED::Object *iCamera, RED::GI_CACHE_MODE iMode, const RED::Vector<RED::Vector3> &iFilteringPositions, const RED::Vector<RED::Object*> &iExcludedObjects, const RED::Vector<RED::Object*> &iSampleBlockingObjects, float iFeedbackInterval = 500.0f) = 0
GI cache pre-processing method.
Pre-processes the irradiance cache using available CPUs for the specified camera scene. The irradiance cache stores all global illumination results and is processed in a view dependent or independent manner for a later replay by the CPU or by the GPU.
The method provides no visual feedback and is a potentially very long blocking call. A progress indicator can be retrieved thanks to the progress indicator callback (see RED::IWindow::SetRenderingProgressCallback).
The RED::OPTIONS_RAY_ENABLE_SOFT_TRACER option has to be enabled on the cluster’s resource manager for this method to work properly. This indicates that the engine must do the necessary setup to render frames using only the CPU.
Once calculated, the results are stored in oGICache and can be reused by assigning the GI cache to a camera through RED::IViewpointRenderList::SetViewpointGICaches.
Please note that if iCamera is inserted into several VRLs of the window, the GI cache will be calculated only for the last VRL of the window list.
This method can be used to enhance an existing GI cache. To do so, the existing GI cache must be set on the VRL using RED::IViewpointRenderList::SetViewpointGICaches. Then, this method will return oGICache set to that existing GI cache address. The contents of the GI cache will have been merged with the samples generated for the specified camera position.
The returned GI cache implements the RED::IGICache interface.
- Parameters
oComplete – Returned true if the rendering of the GI cache is finished.
oGICache – The generated GI cache object. This object must be destroyed by the caller once it has been used and is no longer needed using RED::Factory::DeleteInstance. The return value is only set when the calculation is completed. Otherwise, oGICache is set to NULL during the calculation loop.
iCamera – The camera from which to compute the GI cache. This camera must be part of the window cameras.
iMode – If this flag is set to RED::GICM_CAMERA_VIEW
, the irradiance cache is processed for the camera field of view only.
If this flag is set to
RED::GICM_CAMERA_SPHERICAL, the irradiance cache is processed for the full set of directions around the camera position. This latter allows for the rendering of 360-degrees GI cache that can be later used to render panoramas with global illumination.
If this flag is set to
RED::GICM_WORLD, the irradiance cache is processed for the whole scene, creating samples everywhere.iFilteringPositions – Optional list of GI cache samples filtering positions. Each position is interpreted as the position of a spherical camera and is used to check GI cache samples visibility. The filtering occurs only in world GI cache mode for which filtering positions are used to define GI cache samples that are defined based on the visibility of at least one sample in the list. Filtering positions can be seen through transparent objects, except for those specified in the iSampleBlockingObjects list.
iExcludedObjects – Optional list of shapes that are excluded from the GI cache samples distribution in world mode. Leaf objects are supplied in this list and all found instances of these objects are removed from the GI cache samples distribution. This exclusion occurs only in world GI cache mode.
iSampleBlockingObjects – Optional list of shapes that prevent filtering positions to be visible through them, regardless of their transparency.
iFeedbackInterval – Feedback interval.
- Returns
RED_OK if the method has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_BAD_PARAM if iCamera is not found in the list of cameras in the window,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WFLOW_SOFT_TRACER_IS_DISABLED if the soft tracer is disabled,
RED_INTERRUPT on a user interruption. A call to
RED::IWindow::FrameTracingStopmust occur after an interruption to complete the frame that is interrupted.
RED_FAIL otherwise,
Other return codes are possible due to the many deferred operations resulting of this method’s call.
-
virtual RED_RC FrameTracingImages(bool &oComplete, const RED::Vector<RED::Object*> &iImages, const RED::Vector<RED::Object*> &iViewpoints, RED::FRAME_TRACING_FEEDBACK iMinFeedback = RED::FTF_BY_SURFACE_LEVEL_0, float iFeedbackInterval = 500.0f) = 0
Progressive software ray-tracing rendering method that also returns rendered images.
Image rendering is only a part of the way to final image production. Most of the time, post-processing operators must be applied to the images to increase their quality, level of realism, or just display them onto the screen.
REDsdk already provides some useful post-processing filters for most common tasks, but expert users may want to apply custom post-processing operations to their images. More generally, everyone doing tiled rendering needs this method in order to perform correct tone mapping.
Tone mapping operators all need the average luminance of the image prior to processing it. After having rendered each tile separately, the user may want to extract from them the overall image luminance by calling RED::IImage::ComputeAverageLuminance on the tile raw renderings list. Finally, call RED::IWindowFrameDrawing on each tile to apply the selected tone mapping operator.
This method fills in the supplied 2D images in raw format for each requested camera. The raw format corresponds to the image before anti-aliasing and tone mapping with all the information needed to process them.
Exactly two 2D images created by RED::IResourceManager::CreateImage2D must be supplied to iImages for each camera in iViewpoints. Each image must be empty at the time of the call or set with a RED::TGT_TEX_RECT target. All images are the property of the caller and must be deleted by him after use.
Read the RED::IWindow::FrameTracing method documentation for additional details.
- Parameters
oComplete – Returned true if the rendering of all cameras is finished.
iImages – List of 2D images that must be provided for the given list of viewpoints (2 images per viewpoint, one for the color buffer and one for the depth buffer).
iViewpoints – List of the viewpoints for which raw images are requested.
iMinFeedback – The feedback mode chosen for the method. Choose either a RED::FTF_BY_BLOCKS mode (blocky image, better for high quality images) or any RED::FTF_BY_SURFACE_LEVEL_0 or higher mode (clean surface image, better for fast viewporting feedback).
iFeedbackInterval – Interval waited by the engine before returning an image. This value is used to limit the time spent calculating the specified iMinFeedback if a surface feedback is requested, or defines the regular image feedback if a block feedback has been requested in iMinFeedback.
- Returns
RED_OK if the method has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter: if the list of viewpoints is empty or if the list of images for each viewpoint is not correct or if images are not 2D images or if a viewpoint does not belong to the window,
RED_WFLOW_SOFT_TRACER_IS_DISABLED if the software tracer is disabled,
RED_INTERRUPT on a user interruption. A call to
RED::IWindow::FrameTracingStopmust occur after an interruption to complete the frame that is interrupted, or another image can be processed.
As for
RED::IWindow::FrameDrawing, all kinds of return codes can be returned by this method for all deferred operations that are postponed until a rendering starts.
-
virtual RED_RC FrameTracingImageLayers(bool &oComplete, RED::Vector<RED::RenderLayer> &ioLayers, RED::FRAME_TRACING_FEEDBACK iMinFeedback = RED::FTF_BY_SURFACE_LEVEL_0, float iFeedbackInterval = 500.0f) = 0
Progressive software ray-tracing rendering method that also returns rendered images.
This call behaves like RED::IWindow::FrameTracingImages, except that more rendering layers can be generated by the method and returned:
Color and mask layer (mask information is stored in image alpha).
Depth layer.
Object ID layer.
Geometrical normal layer.
Reflection layer.
etc…
See the RED::RenderLayer class description for a complete list of possible rendering layers.
The color image is returned in raw format, before anti-aliasing resolution and before tone-mapping. Each image in a RED::RenderLayer is filled with CPU data. The color and depth layers images are also filled with GPU data if the engine is rendering in hybrid mode. All other rendering layers are pure CPU images that have no GPU contents.
The method provides a direct visual feedback in the VRLs that are hosting the rendering layers only if both the color and depth layers are enabled for the rendering of a given camera. Said otherwise, the results of the image rendering are visible in the window or in the rendered VRLs only if we have the color AND depth information available to display the results.
Each RED::RenderLayer object specifies a render layer to be calculated for a given camera.
- Parameters
oComplete – Returned true if the rendering of all layers for all cameras is finished.
ioLayers – This is the layer of vectors to be processed. A RED::RenderLayer object in this list must contain the specification of a given layer to be processed. It’s returned filled with all the relevant information.
iMinFeedback – The feedback mode chosen for the method. Choose either a RED::FTF_BY_BLOCKS mode (blocky image, better for high quality images) or any RED::FTF_BY_SURFACE_LEVEL_0 or higher mode (clean surface image, better for fast viewporting feedback).
iFeedbackInterval – Interval waited by the engine before returning an image. This value is used to limit the time spent calculating the specified iMinFeedback if a surface feedback is requested, or defines the regular image feedback if a block feedback has been requested in iMinFeedback.
- Returns
RED_OK if the method has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter: if a layer is not correct,
RED_WFLOW_SOFT_TRACER_IS_DISABLED if the software tracer is disabled,
RED_INTERRUPT on a user interruption. A call to
RED::IWindow::FrameTracingStopmust occur after an interruption to complete the frame that is interrupted, or another image can be processed.
As for
RED::IWindow::FrameDrawing, all kinds of return codes can be returned by this method for all deferred operations that are postponed until a rendering starts.
-
virtual RED_RC FramePicking(RED::Vector<RED::ShapePath> &oPickList, const RED::Object *iVRL, int iX, int iY, const RED::LayerSet *iLayerSet, int iStateNumber = -1) = 0
Picks entities in the window.
Call this method to pick geometrical elements “under the mouse” for the specified VRL of the window. Picked results are sorted from closest to farthest in the returned list of RED::ShapePath objects.
The depth sorting of the found intersection is performed from the camera eye position. Note that the RED::OPTIONS_VIEWPOINT_ORTHOGRAPHIC_EYE_AUTO_OFFSET applies if it’s enabled and if the camera is using a parallel projection (see RED::VPT_PARALLEL). In this case, the eye position is shifted according to the description in RED::ShapePath::SortItems.
All viewpoints in the provided VRL are searched for data that can be picked. Viewpoints that are not pickable are ignored.
The lower left VRL corner is at pixel coordinates ( 0, 0 ).
This method performs an graphic primitive level picking: all triangles, lines, points and texts that are found under the mouse are selected, sorted and returned in RED::ShapePath objects instances. There’s one shape path per object instance in the scene graph that has been picked, and all entities that have picked for that object are stored in the shape path for that object.
Performances of this method are better if shapes have bounding spheres.
The size of the picking window can be modified using the RED::OPTIONS_WINDOW_PICK_AREA option. Performances of the picking operation can be affected by the value of the RED::OPTIONS_WINDOW_PICK_AREA_TRIANGLE option.
- Parameters
oPickList – Resulting picked list.
iVRL – VRL of the window to pick in. Only cameras in that VRL are picked.
iX – X window coordinate of the picking to perform.
iY – Y window coordinate of the picking to perform.
iLayerSet – Layer filter to apply to select picked elements. If no valid RED::LayerSet address is provided, the method uses the current camera layerset.
iStateNumber – Queried state number.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_BAD_PARAM if iVRL is not a valid VRL address in the window,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
-
virtual RED_RC FramePickingRectangle(RED::Vector<RED::ShapePath> &oPickList, const RED::Object *iVRL, int iXMin, int iXMax, int iYMin, int iYMax, const RED::LayerSet *iLayerSet, bool iPickOnlyInside = false, bool iPickAllElements = false, int iStateNumber = -1) = 0
Rectangular area picking.
This method performs an object level picking in the data contained in the specified iVRL. Compared to the RED::IWindow::FramePicking method, only objects (e.g. RED::IShape instances) are picked and returned by the method.
Objects that are picked are not sorted. The picking occurs ‘in depth’, in the sense that all objects that are in the picking area are returned, even those that are hidden by some closer other objects.
RED::ShapePath instances are filled for each picked object. However, there’s no information on the primitive items being picked inside an object. The object is returned as a whole, so the RED::ShapePath is filled with one item owning the RED::ShapePath::BOUNDING_SPHERE type of the object or with any one item of the shape that was found inside the picking rectangle.
if the iPickAllElements flag is returned, the method behavior is unchanged, except that the oPickList list of results is filled with all geometrical primitives found in all objects that were picked. As a result, on a large scene, millions of picked entities may be returned. In this case, picked entities details don’t include any pick position in RED::ShapePath::LeafData since hit objects primitives may be partially or fully contained in the rectangular picking area.
Performances of this method are better if shapes have bounding spheres.
If the picked rectangle is invalid, the method returns no result.
- Parameters
oPickList – Resulting picked list.
iVRL – VRL of the window to pick in. Only cameras in that VRL are picked.
iXMin – Minimum x coordinate of the picking rectangle.
iXMax – Maximum x coordinate of the picking rectangle.
iYMin – Minimum y coordinate of the picking rectangle.
iYMax – Maximum y coordinate of the picking rectangle.
iLayerSet – Layer filter to apply to select picked elements. If no valid RED::LayerSet address is provided, the method uses the current camera layerset.
iPickOnlyInside – If set to true, only objects that are fully inside the rectangle are picked. If false, any object that has at least one primitive hitting the rectangle is picked. The method consumes more time if this flag is true.
iPickAllElements – If set to true, all sub-entities of picked shapes are returned in oPickList. By default (iPickAllElements set to false), only picked shapes are returned. If set to true, then the resulting oPickList is filled with all entities found that intersect the rectangle.
iStateNumber – Queried state number.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_BAD_PARAM if iVRL is not a valid VRL address in the window,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
-
virtual RED_RC GetPickLine(RED::Vector3 &oP1, RED::Vector3 &oP2, const RED::Object *iVRL, const RED::Object *iCamera, int iX, int iY, int iStateNumber = -1) const = 0
Retrieves the picking line “under the mouse”.
Picking performed by FramePicking fires a ray from the camera eye position through the window screen coordinates at (iX + 0.5, iY + 0.5).
This method returns the spatial picking line that corresponds to a line picking at (iX + 0.5, iY + 0.5).
- Parameters
oP1 – Starting point of the returned picking line.
oP2 – Ending point of the returned picking line.
iVRL – VRL that contains iCamera. This parameter must be specified as more than one VRL can contain iCamera.
iCamera – Camera source of the picking line.
iX – Picked X integer window coordinate.
iY – Picked Y integer window coordinate.
iStateNumber – Queried transaction number.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_BAD_PARAM if iCamera does not belong to iVRL or if iVRL is not a valid VRL in the window,
RED_BAD_PARAM if iX or iY are outside of the VRL boundaries,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
-
virtual void *GetOSHandler() const = 0
Gets the OS-dependent window handle.
It’s up to the user to cast back the returned handle into the correct OS-dependent window type.
- Returns
The OS-dependent window handler.
-
virtual RED_RC SetOSHandler(void *iNewOSHandle) = 0
Change the OS-dependent window handle.
After creation, the window handle may change over time for various reasons, in the application hosting the window. This method lets you notify REDsdk of the change, so that rendering can be adjusted accordingly.
- Parameters
iNewOSHandle – The new window handle.
- Returns
RED_OK if the method has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
Any RED_DRV_* error code if a graphic error has occurred,
RED_FAIL in the case of an unavailable renderer.
-
virtual const RED::WindowRenderInfo &GetRenderInfo() const = 0
Gets the window hardware configuration parameters.
- Returns
The window’s hardware configuration.
-
virtual RED_RC GetHardwareVendor(const char *&oVendor) = 0
Returns the GPU vendor string id.
This is the result of glGetString(GL_VENDOR) on the graphic card used for the creation of this window.
- Parameters
oVendor – The hardware vendor string.
- Returns
RED_OK when the method has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC GetOpenGLExtensions(const char *&oExtensions) = 0
Gets the OpenGL extensions string.
This is the result of glGetString(GL_EXTENSIONS) on the graphic card used for the creation of this window.
- Parameters
oExtensions – The OpenGL extension string.
- Returns
RED_OK when the method has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC GetRenderer(const char *&oRenderer) = 0
Returns the name of the graphic card.
This is the result of glGetString(GL_RENDERER) on the graphic card used for the creation of this window.
- Returns
oRenderer: The name of the renderer.
- Returns
RED_OK when the method has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC GetOpenGLVersion(const char *&oVersion) = 0
Returns the OpenGL version.
This is the result of glGetString(GL_VERSION) on the graphic card used for the creation of this window.
- Returns
oVersion: The supported OpenGL version.
- Returns
RED_OK when the method has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC IsNVidia(bool &oNVidia) = 0
Is the GPU of the NVidia kind?
- Parameters
oNVidia – true if we run on a NVidia GPU.
- Returns
RED_OK when the method has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC IsATI(bool &oATI) = 0
Is the GPU of the ATI kind?
- Parameters
oATI – true if we run on a ATI GPU.
- Returns
RED_OK when the method has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC IsINTEL(bool &oINTEL) = 0
Is the GPU of the INTEL kind?
- Parameters
oINTEL – true if we run on an INTEL GPU.
- Returns
RED_OK if the method has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC IsNoRayTrace(bool &oNoRayTrace) = 0
Is the GPU capable of any real-time ray-tracing capability?
Very low end GPUs can’t run any real-time ray-tracing feature. Refer to the \ref bk_ba_hardware_platforms page for the list of GPUs that have native rendering limitations.
- Parameters
oNoRayTrace – true is the GPU has no ray-tracing capabilities.
- Returns
RED_OK if the method has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC IsLimitedRayTrace(bool &oLimitedRayTrace) = 0
Is the GPU capable of full real-time raytracing?
Low end GPUs can’t run the whole ray-tracer feature set and are limited to basic shadowing capabilities. Refer to the \ref bk_ba_hardware_platforms page for the list of GPUs that have native rendering limitations.
- Parameters
oLimitedRayTrace – true if the GPU has limited ray-tracer capabilities, false otherwise.
- Returns
RED_OK when the method succeeded,
RED_FAIL otherwise.
-
virtual RED_RC IsLimitedAreaLighting(bool &oLimitedAreaLighting) = 0
Is the GPU capable of rendering area lights?
Low end GPUs can’t render area lights. In this case the engine will dynamically use point lights instead.
- Parameters
oLimitedAreaLighting – true if the GPU can’t render area lights.
- Returns
RED_OK when the method succeeded,
RED_FAIL otherwise.
-
virtual RED_RC IsNativeHDR(bool &oNativeHDR) = 0
Is the GPU capable of native HDR rendering?
Low end GPUs have very limited blending capabilities with floating point buffers. Consequently, the rendering can be very slow when blending operations occur on floating point buffers. The behavior of REDsdk is to prevent a buffer to be turned into HDR for hardware that have no native HDR blending capabilities.
- Parameters
oNativeHDR – true if the GPU has a native HDR capability.
- Returns
RED_OK when the method has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC GetGPUChipset(RED::HARDWARE_PLATFORM &oChipset) = 0
Returns the chipset category of the graphic card used by the application.
This method returns a runtime platform identifier as described in the RED::HARDWARE_PLATFORM enumeration. The returned value defines the chipset category of the GPU(s) used by the application.
- Parameters
oChipset – Returned chipset value in the list of available runtime platform identifiers (user and generic platforms are excluded from possible return values).
- Returns
RED_OK when the method has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC GetMaxTextureSize(int &oMaxTexSize) const = 0
Returns the maximal pixel size a texture can hold along one of its dimensions.
This method returns the ‘value’ of the glGetIntegerv( GL_MAX_TEXTURE_SIZE, &value ) call.
- Parameters
oMaxTexSize – Maximal pixel size of a texture along one of its dimensions.
- Returns
RED_OK if the method has succeeded,
RED_DRV_FAIL if a graphic driver has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetMax3DTextureSize(int &oMax3DTexSize) const = 0
Returns the maximal pixel size a 3D texture can hold along one of its dimensions.
This method returns the ‘value’ of the glGetIntegerv( GL_MAX_3D_TEXTURE_SIZE, &value ) call.
- Parameters
oMax3DTexSize – Maximal pixel size of a 3D texture along one of its dimensions.
- Returns
RED_OK if the method has succeeded,
RED_DRV_FAIL if a graphic driver has occurred,
RED_FAIL otherwise.
-
virtual void SetRenderingProgressCallback(RED::RENDERING_PROGRESS_CALLBACK iCallback, void *iUserData) = 0
Sets the user-defined rendering progress callback.
The engine calls the rendering progress callback all along the rendering of a frame by the engine. All informations returned are stored in a RED::FrameStatistics class whose contents are updated along with the progress of the rendering.
- Parameters
iCallback – Pointer to the user defined rendering progress callback.
iUserData – User data parameter sent to the callback.
-
virtual void GetRenderingProgressCallback(RED::RENDERING_PROGRESS_CALLBACK &oCallback, void *&oUserData) const = 0
Returns the current user rendering progress callback.
- Parameters
oCallback – The current rendering progress callback method.
oUserData – The user data associated to the callback.
-
virtual const RED::FrameStatistics &GetFrameStatistics() const = 0
Returns the current frame statistics.
- Returns
The frame statistics held by the window. This object must be accessed from the rendering thread, after a rendering call has ended, as it’s modified during the draw and it’s not transaction secured.
-
virtual RED_RC SetHostingMetalRenderTarget(void *iMtlColorTexture, void *iMtlDepthStencilTexture) = 0
Set hosting application Metal render target textures.
This method must be called before FrameDrawingRED::IWindow::FrameDrawing.
Note
The given textures dimensions must match the window size.
Note
The given textures must have constant pixel formats during the window lifetime.
- Parameters
iMtlColorTexture – MTLTexture instance to use as the color render target.
iMtlDepthStencilTexture – MTLTexture instance to use as the depth+stencil render target. Can be NULL.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method received an invalid parameter,
RED_FAIL otherwise.
-
virtual RED_RC CopyAndFlipMetalTexture(void *iMtlSourceTexture, void *iMtlDestinationTexture) = 0
Copy and flip bottom-up the source texture into destination.
This method can be called after FrameDrawingRED::IWindow::FrameDrawing.
Note
The given textures dimensions must be equal.
Note
The given textures must have the same pixel formats.
- Parameters
iMtlSourceTexture – MTLTexture instance to use as source.
iMtlDestinationTexture – MTLTexture instance to use as destination.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method received an invalid parameter,
RED_FAIL otherwise.
-
virtual void ReleaseOpenGLContext() = 0
Releases the current OpenGL context owned by the calling thread.
To process advanced OpenGL orders in multi-threaded environments, it may be needed to release the current OpenGL context owned by a thread. This method can be used to do that operation. Practically, the following code is executed:
// On windows platforms: wglMakeCurrent( NULL, NULL ); // On Linux platforms: glXMakeCurrent( display, None, NULL ); // Using the window's display.
-
virtual RED_RC DisplayFPSCounter(bool iOnOff, const RED::State &iState) = 0
Adds a built-in performance display counter to the window.
This method adds a viewpoint to the window, filled with performance counters. The viewpoint appears on the top right of the window, and has a fixed attachment to it.
The method displays two values:
The application time: this is the time spent in the application, outside REDsdk, between two rendering calls. The measure start at the end of FrameDrawing and stops at the beginning of the next FrameDrawing.
The RED engine time: this is the time spent inside REDsdk during the draw. The measure starts at the beginning of FrameDrawing and ends at the end of FrameDrawing.
And displays a synthesis ‘Frame Per Second’ indicator, that corresponds to the total frame rate, including the RED engine time plus the application time.
Note that if the application has a passive window refresh loop, then the application time becomes meaningless as it reflects the time waited by user before provoking the refresh of the window.
- Parameters
iOnOff – Set to true to enable FPS counter display, false to disable the display.
iState – Current transaction.
- Returns
RED_OK when the option succeeded,
RED_ALLOC_FAILURE if an internal allocation did fail,
RED_FAIL otherwise.
-
virtual RED_RC IsFPSCounterDisplay(bool &oOnOff, int iStateNumber = -1) const = 0
Is the FPS counter currently displayed?
- Parameters
oOnOff – true if the FPS counter is displayed, false otherwise.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation succeeded,
RED_FAIL otherwise.
-
virtual RED_RC GetFPSCounter(float &oApplicationTime, float &oREDEngineTime) const = 0
Retrieves FPS counter values.
This method retrieves the two current values of the performance counters, as defined in the RED::IWindow::DisplayFPSCounter method.
- Parameters
oApplicationTime – The time spent in the application since the two last RED::IWindow::FrameDrawing calls.
oREDEngineTime – The time spent in REDsdk since the two last RED::IWindow::FrameDrawing calls.
- Returns
RED_OK if the operation has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC ExtractGICache(RED::Object *&oGICache) = 0
Extract the last defined internal GI cache.
This method is used after a call to RED::IWindow::FrameTracing (or any derived FrameTracingXXX method). It provides an access to the last calculated global illumination cache. The cache is returned by the method and it becomes the property of the caller. Once done, the cache must be destroyed by the application using RED::Factory::DeleteInstance.
If there are several VRLs and / or ray-traced viewpoints in the window, this is the cache of the last calculated viewpoint that is returned. If an external GI cache was set, then no cache is returned by the method.
This method should be called only from the rendering thread.
- Parameters
oGICache – The extracted cache address. NULL if we have no internal cache.
- Returns
RED_OK if the operation has succeeded,
RED_FAIL otherwise.
