REDsdk 4.0
Welcome to REDsdk 4.0. This version is a key milestone in the development of REDsdk. Many new features have been implemented, the API has been homogenized and a full new documentation that you’re actually using has been written.
Don’t get lost! Please follow carefully all the migration steps described in this guide to switch from any older REDsdk version to REDsdk 4.0. Then, our support is at your disposal. We can arrange live coding sessions or in house trainings in our Paris office at your convenience to assist you in migrating to REDsdk 4.0 in a safe and stable way. Don’t hesitate to get in touch with us to plan this work.
We hope you’ll appreciate this new version!
API Changes
For those that directly want to jump into the details, see all API changes here: REDsdk 4.0 API Changes.
Overview of Changes
There are many changes at every level that have occurred in this version of REDsdk. This very first REDsdk 4 release has been focusing on the following global objectives:
Become more accessible.
Render faster.
Be more robust.
We have worked on accessibility: the documentation you’re reading through is the key element that participates to making REDsdk an easier to use product for professionals aiming at developing stunning graphic applications. See all the details below in the New Documentation section. All new tutorials, new search engine, tasks, books and much more await for your eyes.
We have also invested a lot on performances. Both CPU and GPU performances were targeted by this release:
On the software side, we have worked on integrating Embree Ray-Tracing Kernels to improve the performance of REDsdk’s software ray-tracer whenever possible. We have also worked on a New Thread Balance in software rendering, improving significantly the rendering performance on machines with a limited number of CPU cores. Finally, we have entirely reworked the Global Light Cutoff while increasing the size of our calculation buckets (New 32x32 Bucket Size).
On the GPU side, a brand new Super Scale Engine Anti-Aliasing makes engine anti-aliasing as fast as hardware anti-aliasing while keeping its quality intact. Multi Render Target VRLs allow application developers to generate many graphic outputs in one single rendering pass.
In the end, we also added many more features to REDsdk, strengthening its feature set a lot. All these are detailed below. Each of these feature may have an impact on your actual code, so please take your time and carefully read all the paragraphs below before migrating to REDsdk 4.0. If you have any question, we’re at your disposal.
New Documentation
You’re using it right now while reading this page! So what’s really new in there?
First a new organization of all the data contained in the documentation in books, tutorials and tasks. Books are dedicated to a single topic. Tutorials are concrete code examples with executables while tasks are just extract of a few lines of code dedicated to accomplishing something with REDsdk.
New thematic organization in the documentation.
Second a new search engine! While not fulltext, it works very well and will be your daily guide in this new documentation.
A new search engine is available!
Then, related data organization has been added. While navigating to a page, you’ll find related informations in the right column of the page:
Related topics appear in the right column of the documentation.
Finally, quick links bar will let you navigate in the full documentation:
Quick links for an easier navigation.
But most important, we hope that the new contents in the documentation will help you in using REDsdk.
Embree Ray-Tracing Kernels
REDsdk 4.0 integrate Embree ray-tracing kernels. These significantly accelerate the rendering in REDsdk. However, the feature set of Embree is limited compared to REDsdk. Therefore, they can’t be used for all types of images that can be processed by REDsdk. Nevertheless, whenever possible, REDsdk will use Embree. There are new engine options to control REDsdk’s behavior regarding Embree. See all the details in the doc Ray-Tracing Options in the Using Embree section.
New Thread Balance
The default setup of REDsdk’s software ray-tracer was to use one calculating thread per available CPU core. Consequently, a software rendering application used to work with one more thread (the application’s thread) than the number of available CPU cores. On some customer applications, on Windows, this caused problems in the application’s responsiveness due to the saturated CPU cores. Therefore, we have changed the internal behavior of REDsdk. Now the application’s rendering thread is used for both the application feedback AND for software calculations. This enhances the global application performance while this keeps the responsiveness of the application to the maximum.
There’s no API change related to this development.
Global Light Cutoff
The RED::OPTIONS_RAY_PHYSICAL_LIGHT_CUTOFF has been removed and replaced by the RED::OPTIONS_LIGHT_CUTOFF, which is a more generic option that apply to all lights that have an attenuation. Unlike in the previous REDsdk release, the light’s cutoff frontier is smooth, as detailed in the doc Software Display Performances under the Light Cutoff Option section. Using this option greatly increases display performances in environments with many lights.
New 32x32 Bucket Size
REDsdk’s software ray-tracer used to start rendering an image using 16x16 sized buckets. The minimal size of a bucket has been increased to 32x32 allowing a faster first pass to get a complete coverage of the image.
Super Scale Engine Anti-Aliasing
The RED::IViewpointRenderList::SetEngineAntiAlias method has been granted a new ‘iSuperScale’ parameter. This parameter changes the way the engine anti-aliasing works. The two different behaviors are detailed in the doc VRL Anti-Aliasing under the Engine Anti-Aliasing section.
Note
Due to the global migration of REDsdk to OpenGL FBOs, hardware anti-aliasing is no longer supported on auxiliary VRLs. However, this should not cause any problem as the engine anti-aliasing with super scaling produces a better quality with similar performances and memory usage as the hardware anti-aliasing.
Multi-Render Target VRLs
REDsdk 4.0 now allows offscreen buffers (e.g. VRLs) to render to several buffers in one single rendering pass. This is called ‘multiple render targets’ (MRT). This is leveraged by:
Creating a multiple render target buffer using
RED::IWindow::CreateMultiRenderTargetVRL.Rendering data into this VRL with shader programs capable of targeting MRTs.
Accessing the resulting images thanks to
RED::IViewpointRenderList::GetRenderImage, specifying the number of the auxiliary image that needs to be accessed.
Integration of REDNet into REDsdk
REDNet was a product that was separated from REDsdk. It’s now integrated into REDsdk, with no other changes. Therefore, REDNet.dll no longer exists. All the REDNet features are accessible from REDCore.dll. The RNET namespace remains valid and accessible from the same include directory as all other REDsdk headers.
New Light Sampling API
Sampling controls in REDsdk 4.0 have changed. See in the doc Monte Carlo Sampling under the section Sampling Controls in REDsdk and Setup the Rendering for details on new light rendering options.
New Image I/O API.
See the RED::ImageTools class for a simple and convenient API to save LDR or HDR images to disk or to read them back!
Changes in Software Light Parsing Loop
The light sampling loop has been modified to leverage all optimizations delivered along with REDsdk 4.0. Consequently, the former loop based on ‘StartAdaptiveSampling’ is no longer valid. The new loop is detailed here: Iterating Over Lights in a Software Shader.
New Shader Access Method and New Input Parameter API
This is another big change in the shader API that was delivered with REDsdk 4.0. This affects built-in REDsdk shaders. Other shaders are not affected by these changes. Previous REDsdk versions had a complex shader parameter manipulation API: To modify a shader parameter, the caller had to look for the right parameter with the right shading target in the right hardware platform, extract a list of parameters corresponding to these changes and modify them. One of the problems with this approach - in addition to the heavy code - was that depending on the shader parameters, some parameters could be available or not (!) depending on the optimization codepath of the internal shader. This was waaaaay too complex to provide any easy to use mechanism to our customers that often reported headaches to us about this.
So, we decided to change this part of our API. In REDsdk 4.0 if a built-in shader is created, then all the parameters of the construction method have a corresponding parameter name. Let’s look at a concrete example using the RED::RenderShaderSolid shader:
RED::Color color = RED::Color::RED;
RED::RenderShaderSolid solid( RED::MTL_PRELIT,
color, NULL, RED::Matrix::IDENTITY, RED::MCL_TEX0,
RED::Color::WHITE, NULL, RED::Matrix::IDENTITY, RED::MCL_TEX0,
resmgr, rc );
In previous REDsdk versions, this shader could not be set to use a texture without recreating it. The fact that it was color based implied that only that color could be modified. Now this has changed. Any parameter provided to the shader can be modified using the new input parameter API available from the RED::RenderShader class:
// Assuming that we want to set a texture 'image' with a 'matrix', we do:
RC_TEST( solid.SetInputParameter( matrix, RED_RSH_SOLID_OBJECT_MATRIX, resmgr ) );
RC_TEST( solid.SetInputParameter( image, RED_RSH_SOLID_OBJECT_TEXTURE, resmgr ) );
So this gets a lot easier to manipulate built-in REDsdk shaders. Modifying an input parameter produces the same result as recreating the shader with the modified parameter.
Legacy .red files that contain built-in shaders will not load as shaders with built-in parameters: this mean that modifying a shader loaded from a REDsdk 3.5 .red file will use the ancient system, using legacy parameter names available from REDsdk 3.5. This applies to all former REDsdk releases as well. We know this can be a big change. Don’t hesitate to contact us to get our assistance in migrating this part of your source code. We’ll gladly help you in solving this out as quickly as possible.
Data Manager API Migration
The RED::IDataManager API has been modified to comply to the coding rule that states that output parameters come first in the list of parameters of a given method. This was definitely not the case with the data manager. We do mention this migration explicitly here because several data manager methods remain compatible after a parameter swap, so this will NOT cause any compilation error to be raised. However, runtime errors will be raised as the meaning of the parameters can’t be swapped either. So any usage of the RED::IDataManager should be carefully reviewed.
New OpenGL Texture ID Access API
This simple new API lets any application access the internal texture IDs of a REDsdk image: RED::IImage2D::GetOpenGLInfo. See the doc Managing Multiple Windows and External OpenGL Contexts under the section Using External OpenGL Contexts in an Application for more details on OpenGL contexts sharing rules that apply in REDsdk when REDsdk is used in a 3rd party OpenGL application.
Previewing Mechanisms and Image Restart
This is also an important change in how REDsdk behaves. Rendering a software image will not be interrupted by new transactions anymore unless something has changed in the software rendered data. This allows applications, for example, to keep one window that is rendering in software while another window is modified. Of course, some isolation must occur at the application level: if the rendered scene graph is modified while it’s rendered, then the rendering will restart to take into consideration new changes. However, if nothing changes in the rendered data, then the rendering will not stop.
In addition to this, a new RED::OPTIONS_RAY_SOFT_PREVIEW has been introduced in this REDsdk release: it allows an application to modify a material in a software rendered image without restarting the rendering from scratch after the change. Please look at the option documentation for further details.
Changes in EndState Synchronization
This change is part of the previewing mechanism described above. All the GPU synchronization and validation of recorded changes occur during the call to RED::IResourceManager::EndState It no longer occurs during the rendering call. Therefore, several transactions can occur consecutively before a draw, which was not authorized before. Note that it’s still bad to do so ;-) One transaction should be defined and then rendered. But this increased flexibility is needed to be able to create transactions for scene graphs that are modified while some others that are rendered are not modified.
New Mesh Primitives API
Finally, we have added some new basic primitives creation calls to the RED::IMeshShape interface: Create boxes, cylinders, cones, etc…easily. This is widely used in all the new REDsdk tutorials.
New Mesh Cutting API
A new RED::IMeshShape::BuildCutMesh method has been added, that can be used to slice a mesh by any number of planes. The cut section meshes and cut contours are reconstructed by the method. See Cutting Geometries: Using Multiple Cutting Planes.
A new RED::IMeshShape::Polygon method has also been added to tessellate a planar face made of closed contours. Interior domains are managed.
New Cross Platform Threading API
The RED::Thread class that was internal goes public. It can be used to start and manage multiple threads. It works on Windows, Linux and MacOS.
