// This file is used solely to put useful information on the main // index page produced by doxygen. /*! \page hdEmbree_page_front HdEmbree : Embree-based hydra renderer plugin. \if ( PIXAR_MFB_BUILD ) \mainpage HdEmbree : Embree-based hydra renderer plugin. \publicLib \endif \anchor hdEmbree_mainpage ## Classes - HdEmbreeConfig - HdEmbreeInstancer - HdEmbreeMesh - HdEmbreeRendererPlugin - HdEmbreeRenderDelegate - HdEmbreeRenderParam - HdEmbreeRenderPass - HdEmbreeRenderer ## Overview HdEmbree implements a Hydra renderer plugin based on Intel's Embree raytracing kernels. HdEmbree is provided as a minimal example of how to write a renderer plugin for hydra; it aims to be living documentation of that API. The embree API is prefixed by "rtc", for raytracing core, and documentation is available [here](https://embree.github.io/api.html). The hydra image generation algorithm (as implemented in HdEngine::Execute) has three main phases: sync, commit resources, and execution of tasks. At each point, hydra delegates some responsibility to the renderer plugin. ## Sync Hydra tracks scene state in the HdRenderIndex datastructure. Before generating images, hydra updates scene state with HdRenderIndex::SyncAll(). Each prim (scene object) is bound to an HdSceneDelegate object, which acts as its datasource; SyncAll loops through each prim calling Sync(), which pulls new scene data from the scene delegate and updates the renderable representation. The render index uses an instance of HdRenderDelegate to create prim classes, and render delegates are specialized for each renderer so that they can create the appropriate renderable representation. HdEmbree provides HdEmbreeRenderDelegate, which can create HdEmbreeInstancer and HdEmbreeMesh. Together, these classes insert mesh objects and mesh instances into the embree scene, so that drawing code can raycast against them. In order to support the standard hydra render task, HdxRenderTask, the scene delegate also supports a basic camera type, HdCamera. ## Commit Resources After updating the render index, but before running tasks, HdEngine::Execute() calls the render delegate's CommitResources(). This gives the renderer a chance to commit the results of the sync phase, e.g. by copying buffers to the GPU or doing a final rebuild of intersection datastructures. HdEmbree doesn't use this, instead deferring bvh rebuilds to the next Render() call. ## Executing tasks The last phase of HdEngine::Execute() is running tasks. Hydra tasks are schedulable callbacks that can be used to render, to maintain scene state, or to interleave execution with other renderers or libraries. Hydra provides HdxRenderTask as a way to simply render a scene. HdxRenderTask takes a collection and render parameters as inputs, and maps them to a render pass, created by the render delegate. Collections specify which parts of the scene to draw (by include/exclude paths), and how to draw them (via the repr token). HdEmbree provides HdEmbreeRenderPass, which draws by raycasting into the embree scene that's been populated by HdEmbree prim objects. The raycasting is done in the helper HdEmbreeRenderer class. Outputs are written into HdRenderBuffer objects, which represent image data. Typically, auxiliary tasks in hdx will blit these into the GL framebuffer. Note: HdEmbreeRenderPass currently doesn't support collection include/exclude paths, so it draws everything in every renderpass. Rendering with multiple embree render passes is unsupported, since they'll write over each other instead of compositing. ## Renderer Plugin HdEmbree fits into the hydra runtime as a plugin, and the discoverable class is HdEmbreeRendererPlugin. The plugin class's only responsibility is to create instances of HdEmbreeRenderDelegate. ## Embree Scene Ownership The embree scene that renderpasses raycast against lives in HdEmbreeRenderDelegate. Because of this, each render index should have a distinct render delegate. The scene is passed to prims during Sync() via the HdEmbreeRenderParam object, and the scene is passed to the renderer object on creation; the renderpass, in turn, gets a handle to the renderer on creation. ## Configuration Embree exports some configuration parameters, controllable by environment variable, through the HdEmbreeConfig class. ## Unit Test testHdEmbree provides an example of how to write a minimal hydra application. It uses HdSt_UnitTestGLDrawing to create a window and provide a GL framebuffer, and Hd_UnitTestDelegate to provide a simple scene graph/data source. The scene is then rendered by running HdxRenderTask via HdEngine::Execute(). */