Urho.Renderer Class

High-level rendering subsystem. Manages drawing of 3D views.

See Also: Renderer

Syntax

public class Renderer : UrhoObject

Remarks

Renderer implements the actual rendering of 3D views each frame, and controls global settings such as texture quality, material quality, specular lighting and shadow map base resolution.

To render, it needs a Scene with an Octree component, and a Camera that does not necessarily have to belong to the scene. The octree stores all visible components (derived from Drawable) to allow querying for them in an accelerated manner. The needed information is collected in a Viewport object, which can be assigned with Renderer.SetViewport method.

By default there is one viewport, but the amount can be increased with the Urho.NumViewports property. The viewport(s) should cover the entire screen or otherwise hall-of-mirrors artifacts may occur. By specifying a zero screen rectangle the whole window will be used automatically. The viewports will be rendered in ascending order, so if you want for example to have a small overlay window on top of the main viewport, use viewport index 0 for the main view, and 1 for the overlay.

Viewports can also be defined for render target textures. See “Auxiliary Views” in the documentation for RendereTarget for details.

Each viewport defines a command sequence for rendering the scene, the RenderPath. By default there exist forward, light pre-pass and deferred render paths in the bin/CoreData/RenderPaths directory, see DefaultRenderPath to set the default for new viewports. If not overridden from the command line, forward rendering is the default. Deferred rendering modes will be advantageous once there is a large number of per-pixel lights affecting each object, but their disadvantages are the lack of hardware multisampling and inability to choose the lighting model per material. In place of multisample antialiasing, a FXAA post-processing edge filter can be used, see the MultipleViewports sample application (bin/Data/Scripts/09_MultipleViewports.as) for an example of how to use.

The steps for rendering each viewport on each frame are roughly the following:

  • Query the octree for visible objects and lights in the camera's view frustum.
  • Check the influence of each visible light on the objects. If the light casts shadows, query the octree for shadowcaster objects.
  • Construct render operations (batches) for the visible objects, according to the scene passes in the render path command sequence.
  • Perform the render path command sequence during the rendering step at the end of the frame.
  • If the scene has a DebugRenderer component and the viewport has debug rendering enabled, render debug geometry last. Can be controlled with Viewport.DrawDebug, default is enabled.

In the default render paths, the rendering operations proceed in the following order:

  • Opaque geometry ambient pass, or G-buffer pass in deferred rendering modes.
  • Opaque geometry per-pixel lighting passes. For shadow casting lights, the shadow map is rendered first.
  • (Light pre-pass only) Opaque geometry material pass, which renders the objects with accumulated per-pixel lighting.
  • Post-opaque pass for custom render ordering such as the skybox.
  • Refractive geometry pass.
  • Transparent geometry pass. Transparent, alpha-blended objects are sorted according to distance and rendered back-to-front to ensure correct blending.
  • Post-alpha pass, can be used for 3D overlays that should appear on top of everything else.

Rendering components

The rendering-related components defined by the Graphics and UI libraries are:

  • Octree: spatial partitioning of Drawables for accelerated visibility queries. Needs to be created to the Scene (root node.)
  • Camera: describes a viewpoint for rendering, including projection parameters (FOV, near/far distance, perspective/orthographic)
  • Drawable: Base class for anything visible.
  • StaticMode: non-skinned geometry. Can LOD transition according to distance.
  • StaticModelGroup: renders several object instances while culling and receiving light as one unit.
  • Skybox: a subclass of StaticModel that appears to always stay in place.
  • AnimatedModel: skinned geometry that can do skeletal and vertex morph animation.
  • AnimationController: drives animations forward automatically and controls animation fade-in/out.
  • BillboardSet: a group of camera-facing billboards, which can have varying sizes, rotations and texture coordinates.
  • ParticleEmitter: a subclass of BillboardSet that emits particle billboards.
  • Light: illuminates the scene. Can optionally cast shadows.
  • Terrain: renders heightmap terrain.
  • CustomGeometry: renders runtime-defined unindexed geometry. The geometry data is not serialized or replicated over the network.
  • DecalSet: renders decal geometry on top of objects.
  • Zone: defines ambient light and fog settings for objects inside the zone volume.
  • Text3D: text that is rendered into the 3D view.

Additionally there are 2D drawable components defined by the Urho2D library.

Optimizations

The following techniques will be used to reduce the amount of CPU and GPU work when rendering. By default they are all on:

  • Software rasterized occlusion: after the octree has been queried for visible objects, the objects that are marked as occluders are rendered on the CPU to a small hierarchical-depth buffer, and it will be used to test the non-occluders for visibility. Use Urho.MaxOccluderTriangles .() and Urho.OccluderSizeThreshold to configure the occlusion rendering. Occlusion testing will always be multithreaded, however occlusion rendering is by default singlethreaded, to allow rejecting subsequent occluders while rendering front-to-back. Use Urho.SetThreadedOcclusion to enable threading also in rendering, however this can actually perform worse in e.g. terrain scenes where terrain patches act as occluders.
  • Hardware instancing: rendering operations with the same geometry, material and light will be grouped together and performed as one draw call if supported. Note that even when instancing is not available, they still benefit from the grouping, as render state only needs to be checked & set once before rendering each group, reducing the CPU cost.

  • Light stencil masking: in forward rendering, before objects lit by a spot or point light are re-rendered additively, the light's bounding shape is rendered to the stencil buffer to ensure pixels outside the light range are not processed.

Note that many more optimization opportunities are possible at the content level, for example using geometry & material LOD, grouping many static objects into one object for less draw calls, minimizing the amount of subgeometries (submeshes) per object for less draw calls, using texture atlases to avoid render state changes, using compressed (and smaller) textures, and setting maximum draw distances for objects, lights and shadows.

Reusing view preparation

In some applications, like stereoscopic VR rendering, one needs to render a slightly different view of the world to separate viewports. Normally this results in the view preparation process (described above) being repeated for each view, which can be costly for CPU performance.

To eliminate the duplicate view preparation cost, you can use Viewport.SetCullCamera .() to instruct a Viewport to use a different camera for culling than rendering. When multiple viewports share the same culling camera, the view preparation will be performed only once.

To work properly, the culling camera's frustum should cover all the views you are rendering using it, or else missing objects may be present. The culling camera should not be using the auto aspect ratio mode, to ensure you stay in full control of its view frustum.


Requirements

Namespace: Urho
Assembly: Urho (in Urho.dll)
Assembly Versions: 1.0.0.0

The members of Urho.Renderer are listed below.

See Also: UrhoObject

Public Constructors

Constructs a new instance of Urho.Renderer which is tied to the Application.CurrentContext.
Constructs a new instance of Urho.Renderer, given a raw pointer to an unmanaged object
Constructs a new instance of Urho.Renderer linked to a specific Context.

Protected Constructors

Empty constructor, chain to this constructor when you provide your own constructor that sets the handle field.

Public Properties

[read-only]
DefaultLightRampTexture2D. Return the default range attenuation texture.
[read-only]
DefaultLightSpotTexture2D. Return the default spotlight attenuation texture.
[read-only]
DefaultMaterialMaterial. Return the default material.
DefaultRenderPathRenderPath. Return default renderpath. Or Set default renderpath.
DefaultTechniqueTechnique. Return default non-textured material technique. Or Set default non-textured material technique.
[read-only]
DefaultZoneZone. Return the default zone.
DrawShadowsBoolean. Return whether drawing shadows is enabled. Or Set shadows on/off.
DynamicInstancingBoolean. Return whether dynamic instancing is in use. Or Set dynamic instancing on/off.
[read-only]
FaceSelectCubeMapTextureCube. Return the shadowed pointlight face selection cube map.
HDRRenderingBoolean. Return whether HDR rendering is enabled. Or Set HDR rendering on/off.
[read-only]
IndirectionCubeMapTextureCube. Return the shadowed pointlight indirection cube map.
[read-only]
InstancingBufferVertexBuffer. Return the instancing vertex buffer
MaterialQualityInt32. Return material quality level. Or Set material quality level. See the QUALITY constants in GraphicsDefs.h.
MaxOccluderTrianglesInt32. Return maximum number of occluder triangles. Or Set maximum number of occluder triangles.
MaxShadowMapsInt32. Return maximum number of shadow maps per resolution. Or Set maximum number of shadow maps created for one resolution. Only has effect if reuse of shadow maps is disabled.
MaxSortedInstancesInt32. Return maximum number of sorted instances per batch group. Or Set maximum number of sorted instances per batch group. If exceeded, instances are rendered unsorted.
MinInstancesInt32. Return minimum number of instances required in a batch group to render as instanced. Or Set minimum number of instances required in a batch group to render as instanced.
MobileNormalOffsetMulSingle. Return shadow normal offset multiplier for mobile platforms. Or Set shadow normal offset multiplier for mobile platforms to counteract possible worse shadow map precision. Default 1.0 (no effect.)
MobileShadowBiasAddSingle. Return shadow depth bias addition for mobile platforms. Or Set shadow depth bias addition for mobile platforms (OpenGL ES.) No effect on desktops. Default 0.0001.
MobileShadowBiasMulSingle. Return shadow depth bias multiplier for mobile platforms. Or Set shadow depth bias multiplier for mobile platforms (OpenGL ES.) No effect on desktops. Default 2.
[read-only]
NumBatchesUInt32. Return number of batches rendered.
NumExtraInstancingBufferElementsInt32. Return number of extra instancing buffer elements. Or Set number of extra instancing buffer elements. Default is 0. Extra 4-vectors are available through TEXCOORD7 and further.
[read-only]
NumPrimitivesUInt32. Return number of primitives rendered.
NumViewportsUInt32. Return number of backbuffer viewports. Or Set number of backbuffer viewports to render.
[read-only]
NumViewsUInt32. Return number of views rendered.
OccluderSizeThresholdSingle. Return occluder screen size threshold. Or Set required screen size (1.0 = full screen) for occluders.
OcclusionBufferSizeInt32. Return occlusion buffer width. Or Set occluder buffer width.
[read-only]
QuadGeometryGeometry. Return quad geometry used in postprocessing.
ReuseShadowMapsBoolean. Return whether shadow maps are reused. Or Set reuse of shadow maps. Default is true. If disabled, also transparent geometry can be shadowed.
[read-only]
ShadowCameraCamera. Allocate a temporary shadow camera and a scene node for it. Is thread-safe.
ShadowMapSizeInt32. Return shadow map resolution. Or Set shadow map resolution.
ShadowQualityShadowQuality. Return shadow quality. Or Set shadow quality mode. See the SHADOWQUALITY constants in GraphicsDefs.h.
ShadowSoftnessSingle. Return shadow softness. Or Set shadow softness, only works when SHADOWQUALITY_BLUR_VSM is used.
SpecularLightingBoolean. Return whether specular lighting is enabled. Or Set specular lighting on/off.
TextureAnisotropyInt32. Return texture anisotropy. Or Set texture anisotropy.
TextureFilterModeTextureFilterMode. Return texture filtering. Or Set texture filtering.
TextureQualityInt32. Return texture quality level. Or Set texture quality level. See the QUALITY constants in GraphicsDefs.h.
ThreadedOcclusionBoolean. Return whether occlusion rendering is threaded. Or Set whether to thread occluder rendering. Default false.
[read-only]
override
TypeStringHash. Urho's type system type.
[read-only]
override
TypeNameString. Urho's low-level type name.
[read-only]
static
TypeNameStaticString. Urho's low-level type name, accessible as a static method.
[read-only]
static
TypeStaticStringHash. Urho's low-level type, accessible as a static method.
VSMMultiSampleInt32. Return VSM shadow multisample level. Or Set VSM shadow map multisampling level. Default 1 (no multisampling.)
[read-only]
VSMShadowParametersVector2. Return VSM shadow parameters.

Public Methods

ApplyShadowMapFilter(View, Texture2D, Single)
DrawDebugGeometry(Boolean)
Add debug geometry to the debug renderer.
static
GetActualView(View) : View
Return a view or its source view if it uses one. Used internally for render statistics.
GetDepthStencil(Int32, Int32, Int32, Boolean) : RenderSurface
Allocate a depth-stencil surface that does not need to be readable. Should only be called during actual rendering, not before.
GetLightGeometry(Light) : Geometry
Return volume geometry for a light.
GetNumGeometries(Boolean) : UInt32
Return number of geometries rendered.
GetNumLights(Boolean) : UInt32
Return number of lights rendered.
GetNumOccluders(Boolean) : UInt32
Return number of occluders rendered.
GetNumShadowMaps(Boolean) : UInt32
Return number of shadow maps rendered.
GetOcclusionBuffer(Camera) : OcclusionBuffer
Allocate an occlusion buffer.
GetPreparedView(Camera) : View
Return a prepared view if exists for the specified camera. Used to avoid duplicate view preparation CPU work.
GetScreenBuffer(Int32, Int32, UInt32, Int32, Boolean, Boolean, Boolean, Boolean, UInt32) : Texture
Allocate a rendertarget or depth-stencil texture for deferred rendering or postprocessing. Should only be called during actual rendering, not before.
GetShadowMap(Light, Camera, UInt32, UInt32) : Texture2D
Allocate a shadow map. If shadow map reuse is disabled, a different map is returned each time.
GetViewport(UInt32) : Viewport
Return backbuffer viewport by index.
OptimizeLightByScissor(Light, Camera)
Optimize a light by scissor rectangle.
OptimizeLightByStencil(Light, Camera)
Optimize a light by marking it to the stencil buffer and setting a stencil test.
QueueRenderSurface(RenderSurface)
Queue a render surface's viewports for rendering. Called by the surface, or by View.
QueueViewport(RenderSurface, Viewport)
Queue a viewport for rendering. Null surface means backbuffer.
ReloadShaders()
Force reload of shaders.
Render()
Render. Called by Engine.
ResizeInstancingBuffer(UInt32) : Boolean
Ensure sufficient size of the instancing vertex buffer. Return true if successful.
RestoreScreenBufferAllocations()
Restore the screen buffer allocation status. Called by View.
SaveScreenBufferAllocations()
Save the screen buffer allocation status. Called by View.
SetCullMode(CullMode, Camera)
Set cull mode while taking possible projection flipping into account.
SetDefaultRenderPath(XmlFile)
Set default renderpath from xml file.
SetViewport(UInt32, Viewport)
Set a backbuffer viewport.
SetVSMShadowParameters(Single, Single)
Set shadow parameters when VSM is used, they help to reduce light bleeding. LightBleeding must be in [0, 1]
StorePreparedView(View, Camera)
Mark a view as prepared by the specified culling camera.
SubscribeToBeginViewRender(Action<BeginViewRenderEventArgs>) : Subscription
Subscribes to the BeginViewRender event raised by the Renderer.
SubscribeToEndViewRender(Action<EndViewRenderEventArgs>) : Subscription
Subscribes to the EndViewRender event raised by the Renderer.
SubscribeToRenderSurfaceUpdate(Action<RenderSurfaceUpdateEventArgs>) : Subscription
Subscribes to the RenderSurfaceUpdate event raised by the Renderer.
Update(Single)
Update for rendering. Called by HandleRenderUpdate().

Public Events