Unit CastleRenderOptions

Shader types.

Values

• stVertex
• stGeometry
• stFragment

What to do when shader uniform variable is set but doesn't exist in the shader. See TGLSLProgram.UniformMissing.

Values

• umWarning: Report that uniform variable not found to WritelnWarning.
• umIgnore: Ignore the fact that uniform variable doesn't exist in the GLSL shader. Do not warn anywhere.

Type of TAbstractColorNode.Mode.

Values

• cmReplace
• cmModulate

Type of ToneMapping.

Values

• tmNone
• tmUncharted: Uncharted 2 tone map. See http://filmicworlds.com/blog/filmic-tonemapping-operators/
• tmHejlRichard: Hejl Richard tone map. See http://filmicworlds.com/blog/filmic-tonemapping-operators/
• tmACES: ACES tone map. See https://knarkowicz.wordpress.com/2016/01/06/aces-filmic-tone-mapping-curve/

Color space. Determines in what color space do we make lighting calculations and do we gamma-correct colors when reading textures and writing to screen. See https://castle-engine.io/color_space .

Values

• csSRGB: Color calculation is done in sRGB color space. That is, gamma correction is not done.

  This results in marginally faster but also incorrect lighting calculation.

  This was the "old, traditional" way of calculating lighting in 3D applications, before linear space (with gamma correction) became popular. Some 3D models and their textures may assume it and can look weird with calculation in linear space.

• csLinearWhenPhysicalMaterial: Color calculation is done in linear space for materials using PBR (TPhysicalMaterialNode), otherwise (for unlit and Phong lighting – TUnlitMaterialNode, TMaterialNode) the calculation is done in sRGB space.

  This is like using csSRGB for TUnlitMaterialNode, TMaterialNode, and csLinear for TPhysicalMaterialNode. It is the default color space for Castle Game Engine, as it means that typical materials in modern 3D models (PBR) will behave nicely, while also keeping backward compatibility (for Phong and unlit materials).

• csLinear: Color calculation is always done in linear space. This results in correct lighting calculation.

  It means that texture colors (like for TPhysicalMaterialNode.BaseTexture or TMaterialNode.DiffuseTexture or TUnlitMaterialNode.EmissiveTexture) are converted from sRGB into linear space before using them (to multiply with material and lighting colors) and at the end the resulting color is converted back from linear to display space (likely sRGB) for proper display.

  See https://castle-engine.io/color_space and https://github.com/michaliskambi/x3d-tests/wiki/Gamma-correction-in-X3D-and-glTF for more details.

  In other words, gamma correction is performed.

Warning: this symbol is deprecated: this was only useful with TCastleRenderOptions.Shaders, which is now deprecated in favor of TCastleRenderOptions.PhongShading

This item has no description.

Values

• srDisable
• srWhenRequired
• srAlways

Possible bump mapping options. Use for TCastleRenderOptions.BumpMapping. See https://castle-engine.io/bump_mapping .

Values

• bmNone: Do not perform bump mapping. The normal map texture is completely ignored.
• bmBasic: Simple bump mapping: use the information in normal map RGB channels to change the normal vector at each pixel. Achieves a realistic "rough" surface look.

  See https://en.wikipedia.org/wiki/Bump_mapping .

• bmParallax: In addition to bmBasic, the texture coordinates are perturbed based on the height map and camera direction, to create illusion of 3D shape instead of flat surface.

  This makes e.g. the bricks on the texture really visible as "standing out", in 3D, from the wall.

  We rely on the height map information which should be in the alpha channel of the normal map texture. The TCastleRenderOptions.BumpMappingParallaxHeight can be used to scale that information.

  See https://en.wikipedia.org/wiki/Parallax_mapping .

• bmSteepParallax: Improves the parallax effect, by tracing the ray as it goes through the height map. This is more costly, but makes the parallax effect better.

  See https://www.casual-effects.com/research/McGuire2005Parallax/index.html .

• bmSteepParallaxShadowing: Improves the bmSteepParallax even more, by adding additional shadow calculation.

  See https://www.casual-effects.com/research/McGuire2005Parallax/index.html .

Possible values of TCastleRenderOptions.Mode.

Values

• rmFull: Normal rendering features. Everything is enabled (as long as other TCastleRenderOptions settings allow them).
• rmSolidColor: Solid color is used for everything. We do not show any color variation, materials, lights, fog, textures on surfaces, alpha test. We still do back-face culling and depth test. The idea is that we "hit" the same pixels as normal rendering (with the exception of alpha test textures, this mode doesn't set up alpha test since it doesn't set up textures). But everything has color TCastleRenderOptions.SolidColor.

  This is useful for special tricks.

• rmDepth: Only the rendering fetures that affect depth buffer work reliably, everything else is undefined (and works as fast as possible). This is suitable if you render only to depth buffer, like for shadow maps.

  It's quite similar to rmSolidColor, except alpha testing must work, so (at least some) textures must be applied over the model.

Values for TCastleRenderOptions.WireframeEffect.

Generally, two other properties may affect the way wireframe is rendered: TCastleRenderOptions.WireframeColor and TCastleRenderOptions.LineWidth, quite self-explanatory.

Values

• weNormal: Default setting, polygons are rendered as filled polygons.
• weWireframeOnly: Polygons are rendered as wireframe.

  LineWidth is used as wireframe line width (regardless of TCastleRenderOptions.Mode).

  Depending on TCastleRenderOptions.Mode value:

  • If TCastleRenderOptions.Mode <> rmFull then WireframeColor is used as wireframe line color.

  • If rmFull, then lines are colored and potentially lighted and textured just like their corresponding triangles would be colored. So you can control lighting using TCastleRenderOptions.Lighting, TCastleRenderOptions.ReceiveSceneLights, TCastleRenderOptions.ReceiveGlobalLights properties, and you can control texturing by TCastleRenderOptions.Textures property.

• weSolidWireframe: The model is rendered as normal, with it's wireframe version visible on top. This is most often called "solid wireframe", since the intention is too see wireframe version of the model but still render shapes solid (e.g. filled polygons with depth test).

  Scene.RenderOptions.WireframeColor and Scene.RenderOptions.LineWidth determine the color and width of lines.

  This is often used together with the RenderOptions.Mode set to rmSolidColor. In such case, Then TCastleRenderOptions.SolidColor determinesthe fill color.

• weSilhouette: The model is rendered as normal, with silhouette outlined around it. This works quite like weSolidWireframe, except that weSolidWireframe makes the wireframe mesh slightly in front the model, while weSilhouette makes the wireframe mesh slightly at the back of the model. This way only the silhouette is visible from the wireframe rendering.

  Scene.RenderOptions.WireframeColor and Scene.RenderOptions.LineWidth determine the color and width of silhouette lines.

  This is often used together with the RenderOptions.Mode set to rmSolidColor. In such case, Then TCastleRenderOptions.SolidColor determinesthe fill color.

Values for TCastleRenderOptions.ShadowSampling.

Values

• ssSimple: One sample to shadow map.
• ssPCF4: Percentage Closer Filtering improve shadow maps look, by sampling the depth map a couple of times. They also make shadow more blurry (increase shadow map size to counteract this), and a little slower. They may also introduce new artifacts (due to bad interaction with the "polygon offset" of shadow map).
• ssPCF4Bilinear
• ssPCF16
• ssVarianceShadowMaps: Variance Shadow Maps, see http://www.punkuser.net/vsm/ . This may generally produce superior results, as shadow maps can be then filtered like normal textures (bilinear, mipmaps, anisotropic filtering). So shadows look much nicer from very close and very far distances. However, this requires new GPU, and may cause artifacts on some scenes.

Texture minification filter (what happens when many texture pixels are squeezed in one screen pixel).

Values

• minNearest
• minLinear
• minNearestMipmapNearest
• minNearestMipmapLinear
• minLinearMipmapNearest
• minLinearMipmapLinear
• minDefault: Interpretation of this filter depends on current Scene.RenderOptions.MinificationFilter. If that is also minDefault, it depends on current TCastleRenderOptions.DefaultMinificationFilter.
• minFastest: Alias for minNearest.
• minNicest: Alias for minLinearMipmapLinear.

This item has no description.

Texture magnification filter (what happens when a single texture pixel in stretched over many screen pixels).

Values

• magNearest
• magLinear
• magDefault: Interpretation of this filter depends on current Scene.RenderOptions.MagnificationFilter. If that is also magDefault, it depends on current TCastleRenderOptions.DefaultMagnificationFilter.
• magFastest: Alias for magnNearest.
• magNicest: Alias for magLinear.

This item has no description.

This item has no description.

Values

• bsSrcAlpha
• bsOneMinusSrcAlpha
• bsZero
• bsOne
• bsDstColor
• bsSrcColor: As a source factor only since GL 1.4, check GLFeatures.Version_1_4
• bsDstAlpha
• bsOneMinusDstColor
• bsOneMinusSrcColor: As a source factor only since GL 1.4, check GLFeatures.Version_1_4
• bsOneMinusDstAlpha
• bsSrcAlphaSaturate
• bsConstantColor
• bsOneMinusConstantColor
• bsConstantAlpha
• bsOneMinusConstantAlpha

This item has no description.

Values

• bdSrcAlpha
• bdOneMinusSrcAlpha
• bdZero
• bdOne
• bdDstColor: As a destination factor only since GL 1.4, check GLFeatures.Version_1_4
• bdSrcColor
• bdDstAlpha
• bdOneMinusDstColor: As a destination factor only since GL 1.4, check GLFeatures.Version_1_4
• bdOneMinusSrcColor
• bdOneMinusDstAlpha
• bdConstantColor
• bdOneMinusConstantColor
• bdConstantAlpha
• bdOneMinusConstantAlpha

Various ways to sort the shapes.

Used to define blending sort TCastleViewport.BlendingSort to correctly render partially-transparent objects. See https://castle-engine.io/blending .

Used to suggest blending sort from X3D too, TNavigationInfoNode.BlendingSort.

Used to define occlusion sort TCastleViewport.OcclusionSort to optimize rendering.

Values

• sortAuto: Automatically determine the best sorting method. See the documentation of each usage ( TCastleViewport.BlendingSort , TNavigationInfoNode.BlendingSort , TCastleViewport.OcclusionSort ) about what this exactly means.
• sortNone: Do not sort. If used for blending sort, this will cause artifacts if multiple partially-transparent objects may be visible on top of each other. Unless you manually change the order of shapes / scenes in Viewport.Items.
• sort2D: Sort objects by their Z coordinate (independent from camera).

  This is good and fast for 2D worlds, with flat 2D objects that have zero (or near-zero) size in the Z axis, and they are moved in the Z axis to specify which is in front of another.

  More precisely, we take the minimum bounding box Z coordinate of two objects. (We don't bother calculating the middle Z coordinate, as we assume that the bounding box is infinitely small along the Z axis.) The one with larger Z coordinate is considered to be closer, this is consistent with the right-handed coordinate system.

  Note that the camera position doesn't matter for this sorting. So the 2D object will look OK, even if viewed from an angle, even if viewed from the other side.

• sort3D: Sort objects by the (3D) distance of their bounding box to the camera. This is the best universal sorting method for 3D scenes with many partially-transparent objects.

  The distance is measured from the middle of the bounding box, projected along the camera direction. Note that we do not measure strictly distance to the camera position, we measure distance to the point projected on camera direction. The difference is subtle, and it means that sorting makes sense even for models like Spine (with multiple thin layers that have various 3D coordinates) as long as they are billboards oriented towards the camera with TCastleBillboard.MatchCameraDirection = True and TCastleBillboard.AxisOfRotation = zero.

• sort3DVerticalBillboards: Sort objects by the (3D) distance of their bounding box to the camera, looking at camera direction projected on Y=0 plane.

  This is a good sorting method for 3D when the camera looking more upward or downward should not change the order. In particular, this sorting makes sense for models like Spine (with multiple thin layers that have various 3D coordinates) as long as they are billboards oriented towards the camera with TCastleBillboard.MatchCameraDirection = True and TCastleBillboard.AxisOfRotation = +Y (0, 1, 0).

• sort3DOrigin:

  Warning: this symbol is deprecated.

  Sort objects by the (3D) distance of their origin point (point (0,0,0) in local coordinates) to the camera. This is a useful sorting method for 3D scenes with many partially-transparent objects.

  This is an alternative to sort3D, it is more under your control (because the origin doesn't change e.g. because of animations or using TCastleBillboard, contrary to bounding box, see https://github.com/castle-engine/castle-engine/issues/427#issuecomment-1365862663 ). The downside is that you need to be more aware where is your object origin.

  Just like sort3D, this is measured by projecting the point on the camera direction, instead of measuring the distance to the camera position.

  Deprecated, in most pratical applications now sort3D or sort3DVerticalBillboards will be good.

• sort3DGround:

  Warning: this symbol is deprecated.

  Sort objects by the (3D) distance of their origin point (point (0,0,0) in local coordinates) to the camera, projected on the ground (Y=0).

  Similar to sort3DOrigin, but the height of the object (above Y) doesn't matter.

  Just like sort3D, this is measured by projecting the point on the camera direction, instead of measuring the distance to the camera position.

  Deprecated, in most pratical applications now sort3DVerticalBillboards or sort3D will be good.

• sortCustom: Use TCastleViewport.OnCustomShapeSort. If this event is not assigned, this is equivalent to sortNone.

Like TShapeSort, but doesn't allow sortAuto value.

Warning: this symbol is deprecated: use TShapeSort

This item has no description.

This item has no description.

This item has no description.

Render layer for TCastleTransform.RenderLayer.

Values

• rlParent
• rlBack
• rlFront

Supported line types (patterns), for TLinePropertiesNode.LineType or TRenderContext.LineType.

Values

• ltSolid
• ltDashed
• ltDotted
• ltDashedDotted
• ltDashDotDot

Possible color channel to write, see TCastleRenderOptions.InternalColorChannels.

Possible subset of color channels to write, see TCastleRenderOptions.InternalColorChannels.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

Names for TBlendingSourceFactor used by TBlendModeNode when it is read/written in X3D file. Deliberately compatible with (a subset of) X3DOM BlendMode specification on https://doc.x3dom.org/author/Shape/BlendMode.html .

Names for TBlendingDestinationFactor used by TBlendModeNode when it is read/written in X3D file. Deliberately compatible with (a subset of) X3DOM BlendMode specification on https://doc.x3dom.org/author/Shape/BlendMode.html .

'SRC_ALPHA_SATURATE', // NOT SUPPORTED AS DESTINATION FACTOR

Default for TCastleWindow.StencilBits and TCastleControl.StencilBits.

Non-zero now, which means that in both TCastleWindow and TCastleControl, shadow volumes should work by default.

Note that TCastleWindow implementation makes a smooth fallback: if we cannot get stencil, we retry initialization without stencil buffer. This way we will open the window reliably, and in the worst case – shadow volumes will not work.

This item has no description.

Warning: this symbol is deprecated: use sortNone

This item has no description.

Warning: this symbol is deprecated: use sort3D

This item has no description.

Warning: this symbol is deprecated: use sort2D

This item has no description.

Warning: this symbol is deprecated: use sort3DOrigin

This item has no description.

Warning: this symbol is deprecated: use sort3DGround

This item has no description.

Log shadow volume information. See https://castle-engine.io/manual_log.php about the log.

Determines if color calculation is done in linear space (thus performing gamma correction when reading textures and when storing pixel color to screen) or sRGB (thus not performing gamma correction).

Using linear color space follows reality better and is advised for modern games.

Whatever you choose, your assets (their colors and textures) have to be prepared with the given color space in mind.

See https://castle-engine.io/color_space and possible TColorSpace values documentation.

Change the colors you render, to make them visually better.

Contrary to ColorSpace, tone mapping is not about realism. It's just about changing all colors using some visually-pleasing equation. Just as with <iColorSpace, tone mapping is applied to TCastleScene rendering. It doesn't affect UI rendering.

Do you want to implement your own color-changing operation? There are two ways to process colors with shaders:

1. You can define your own color processing using our compositing shaders ( https://castle-engine.io/compositing_shaders.php ), use PLUG_fragment_modify ( https://castle-engine.io/compositing_shaders_doc/html/section.fragment_plugs.html ). See https://github.com/castle-engine/demo-models/blob/master/compositing_shaders/tone_mapping.x3dv example.

2. You can use screen effects (see https://castle-engine.io/x3d_extensions_screen_effects.php ) to apply post-processing in screen space.

)

Force given rendering for all scenes, if not weNormal.