Class TCastleRenderOptions

Enable real-time lighting when rendering.

Source: base/castlerenderoptions_renderoptions.inc (line 212).

Use lights defined in this scene (in the model loaded to this TCastleScene) to light the shapes in this scene.

Note: This property controls whether lights defined within a model (TCastleScene) affect the shapes in the same model. In case of such lights, the value of TCastleScene.CastGlobalLights and ReceiveGlobalLights doesn't matter. Only this property, ReceiveSceneLights, controls whether such lights work.

The other lights are controlled by ReceiveGlobalLights.

This doesn't matter if Lighting is False. Also, if both ReceiveSceneLights and ReceiveGlobalLights are False, then the scene receives no lighting at all.

Source: base/castlerenderoptions_renderoptions.inc (line 228).

Use lights defined in other scenes to light the shapes in this scene.

This property controls whether other scenes with TCastleScene.CastGlobalLights, as well as headlight, shine on this scene.

This doesn't matter if Lighting is False. Also, if both ReceiveSceneLights and ReceiveGlobalLights are False, then the scene receives no lighting at all.

Source: base/castlerenderoptions_renderoptions.inc (line 240).

Use textures.

Source: base/castlerenderoptions_renderoptions.inc (line 244).

Default minification and magnification filters for textures. These can be overridden on a per-texture basis in VRML / X3D files by X3D TextureProperties node (see X3D specification).

They can be equal to minDefault, magDefault in which case they actually use the values from DefaultMinificationFilter, DefaultMagnificationFilter (by default minLinearMipmapLinear, magLinear).

Source: base/castlerenderoptions_renderoptions.inc (line 257).

This item has no description.

Source: base/castlerenderoptions_renderoptions.inc (line 259).

Size of points. This has an effect on TPointSetNode rendering. Must be > 0.

Source: base/castlerenderoptions_renderoptions.inc (line 265).

Line width. This has an effect on TLineSetNode rendering, and on wireframe rendering when TCastleRenderOptions.WireframeEffect indicates it. Must be > 0.

Source: base/castlerenderoptions_renderoptions.inc (line 271).

Use bump mapping. The bump mapping is only done when particular shape defines a normal map (and a height map, if you want parallax bump mapping). See https://castle-engine.io/bump_mapping .

The normal map is usually provided in the TAbstractOneSidedMaterialNode.NormalTexture field. TAbstractOneSidedMaterialNode is an ancestor of all useful material nodes, like TMaterialNode (Phong lighting), TPhysicalMaterialNode (PBR lighting), and even TUnlitMaterialNode (unlit – doesn't use normals for lighting, but may still use them e.g. for tex coord generation). So all material nodes allow to specify normal map.

See TBumpMapping for various possible values.

Source: base/castlerenderoptions_renderoptions.inc (line 288).

Maximum height expressed in the normal map alpha channel, used only when BumpMapping indicates one of the "parallax" options.

By default this is ignored because BumpMapping by default is just bmBasic, which ignores the height map in the normal map alpha channel. If your normal map includes an alpha channel, and you set BumpMapping to a value bmParallax, bmSteepParallax, bmSteepParallaxShadowing then this property is used to interpret the height information.

Source: base/castlerenderoptions_renderoptions.inc (line 299).

Whether to use Phong shading by default.

Note that each shape may override it by TAbstractShapeNode.Shading field.

Note that Phong shading is forced anyway by various situations:

• PBR materials (TPhysicalMaterialNode, in particular imported from glTF)

• Using textures like normal maps, specular maps

• Using shadow maps

Source: base/castlerenderoptions_renderoptions.inc (line 315).

Shadow maps sampling. Various approaches result in various quality and speed.

Source: base/castlerenderoptions_renderoptions.inc (line 319).

For efficiency reasons, we only allow a finite number of lights that can affect the given shape.

You can increase this number if necessary, although note that it is alreday quite large by default. Instead of increasing this limit, it is always more efficient to design your scenes to fit within this limit. Use the light source radius and/or scope (e.g. you can use "radius" in Blender, it is exported OK to glTF), and make smaller shapes.

Note that on ancient dekstops, with fixed-function OpenGL pipeline, there is an additional hard limit (dependent on GPU, but usually 8, for this). But on modern desktops, as well as mobile and other platforms, you can increase this limit freely.

Source: base/castlerenderoptions_renderoptions.inc (line 337).

Render partially transparent objects.

More precisely: if this is True, all shapes with transparent materials or textures with non-trivial (not only yes/no) alpha channel will be rendered using blending. See https://castle-engine.io/blending for details how it works.

If this is False, everything will be rendered as opaque.

Source: base/castlerenderoptions_renderoptions.inc (line 349).

Blending function parameters, used when Blending.

See https://castle-engine.io/blending for more information about blending.

For the exact meaning of BlendingSourceFactor and BlendingDestinationFactor consult OpenGL specification of glBlendFunc, https://registry.khronos.org/OpenGL-Refpages/gl4/html/glBlendFunc.xhtml . Regardless of whether we use OpenGL for rendering, these properties and their values will reflect the equations there.

The typical blending setup (default) is to use

• BlendingSourceFactor = DefaultBlendingSourceFactor = bsSrcAlpha.

• BlendingDestinationFactor = DefaultBlendingDestinationFactor = bdOneMinusSrcAlpha.

This is the standard that follows most intuitive transparency equation. The major drawback of this default (and why you may want to consider alternatives) is that it depends on a correct order of rendering partially-transparent shapes.

CGE allows to cope with it:

1. When multiple transparent shapes are possible, sort the transparent shapes, using TCastleViewport.BlendingSort.

   Note that it cannot be perfect in certain cases (like when transparent shape is one, concave, mesh).

2. For closed convex 3D objects, use backface culling.

   To do this, set on geometries TAbstractGeometryNode.Solid to True, this activates backface culling.

   In practice you usually set this in a 3D authoring application, like Blender. This is called just "Backface Culling" in Blender, checkbox is in the Blender material properties. This information is then exported to glTF or X3D and just used by CGE.

3. Finally, consider a different blending equation:

   Changing BlendingDestinationFactor to bdOne means that sorting isn't necessary. On the other hand, it only adds to the color, often making too bright results.

Note that these properties can be overridden on each shape using TBlendModeNode. See https://castle-engine.io/x3d_extensions.php#section_ext_blending for details of TBlendModeNode.

Source: base/castlerenderoptions_renderoptions.inc (line 417).

This item has no description.

Source: base/castlerenderoptions_renderoptions.inc (line 420).

Activate various effects related to wireframe rendering. When this is weNormal (default), we simply render polygons as polygons. See description of TWireframeEffect for what other modes do.

Note: How the wireframe effects work when Mode = rmDepth is undefined now. Don't use Mode = rmDepth with WireframeEffect <> weNormal.

Source: base/castlerenderoptions_renderoptions.inc (line 431).

Depth scale in SolidWireframeScale and depth bias in SolidWireframeBias are used to render the mesh when WireframeEffect = weSolidWireframe.

Larger values will "push forward" the rendered mesh a bit, meaning that the wireframe will be more clearly visible in front of it.

To explain it best, understand how rendering with WireframeEffect = weSolidWireframe is done:

1. First we render the object polygons but with polygon offset applied.

   The "polygon offset" parameters SolidWireframeScale and SolidWireframeBias control how much this polygon offset pushes the mesh "back" (behind the wireframe rendered in the 2nd pass). Their exact intepretation is GPU-specific and is exactly like OpenGL glPolygonOffset.

2. Then we render the wireframe version of the object, without any polygon offset applied.

Source: base/castlerenderoptions_renderoptions.inc (line 460).

See SolidWireframeScale for explanation.

Source: base/castlerenderoptions_renderoptions.inc (line 464).

Depth scale in SilhouetteScale and depth bias in SilhouetteBias are used to render the silhouette when WireframeEffect = weSilhouette. Larger values will "push back" the rendered lines a bit, meaning that the effect will more clearly outline the object, and not look like a wireframe over the object.

To explain it best, understand how rendering with WireframeEffect = weSilhouette is done:

1. First we render the object as usual. No polygon offset, and the mesh is renderer in normal way – polygons are polygons.

2. Then we render the wireframe version of the object, with the polygon offset applied.

   The "polygon offset" parameters SilhouetteScale and SilhouetteBias control how much this polygon offset pushes the lines "back" (behind the object rendered in the 1st pass). Their exact intepretation is GPU-specific and is exactly like OpenGL glPolygonOffset.

When both SilhouetteScale and SilhouetteBias are zero, the wireframe is rendered with the same depth as a regular object, and it's undefined which one will be visible . Most likely it will look similar to WireframeEffect = weSolidWireframe actually.

When both SilhouetteScale and SilhouetteBias are > zero, then only the lines that are "silhouettes" will be visible – other lines will be hidden by the object rendered in the 1st pass. You can make the effect more or less "subtle" by changing these parameters.

Source: base/castlerenderoptions_renderoptions.inc (line 505).

See SilhouetteScale for explanation.

Source: base/castlerenderoptions_renderoptions.inc (line 509).

Support lighting and backface culling for models using negative scale. This has a small performance cost, and so is disabled by default.

Source: base/castlerenderoptions_renderoptions.inc (line 514).

Use this scene as a shadow caster for shadow volumes, regardless of whether it is detected as 2-manifold.

Note: The engine automatically detects if a scene is 2-manifold, which can mean that:

1. Either each shape is a 2-manifold (most optimal, as then each shape can be an independent shadow caster for shadow volumes)

2. Or some shapes are not 2-manifold, but a whole scene is 2-manifold (so shapes are maybe not 2-manifold, but all shapes' border edges match with each other, closing the skin of the model perfectly; you can test what was detected looking at TCastleSceneCore.InternalDetectedWholeSceneManifold).

   The "only whole scene is 2-manifold" causes a little different optimization than "each shape is 2-manifold" (because in the former case, we have to render shadow quads for either the whole scene, or not; in the latter case, rendering shadow quads is a per-shape decision).

   But from the usage point of view, both cases are similar, the scene "works as a shadow caster for shadow volumes" automatically.

If the engine detected that scene is 2-manifold (regardless of whether each shape was 2-manifold or only whole scene is 2-manifold) then using this property is not necessary.

Setting this property to True makes sense in 2 cases:

1. You want to speedup loading of this scene, by skipping the automatic detection done by TCastleSceneCore.InternalDetectedWholeSceneManifold.

2. Or if engine detected that this scene is not 2-manifold (so TCastleSceneCore.InternalDetectedWholeSceneManifold = False and some shapes have border egdes), but you want to force using it as shadow caster anyway. In such case, set this to True. Rendering artifacts are possible in such case, but in some cases they may be not noticeable. See https://castle-engine.io/shadow_volumes about using shadow volumes and the requirement to be 2-manifold.

Source: base/castlerenderoptions_renderoptions.inc (line 571).

Enable using GPU shaders to animate skinned models. This is advised, as it increases performance of skinned. There are however certain cases when disabling this may be necessary: https://castle-engine.io/gltf#_alternative_solution_force_recalculating_precise_octree_every_frame

Note that in certain cases, skinned animation on GPU is disabled even when this property is True. This includes: when we use shadow volumes or when GPU is not capable enough.

Source: base/castlerenderoptions_renderoptions.inc (line 582).

WireframeColor that can be visually edited in Castle Game Engine Editor, Lazarus and Delphi. Normal user code does not need to deal with this, instead read or write WireframeColor directly.

See also

WireframeColor

Wireframe color, used with some WireframeEffect values.

Source: base/auto_generated_persistent_vectors/tcastlerenderoptions_persistent_vectors.inc (line 37).