Unit CastleRenderOptions

Description

Configure rendering options. The TCastleRenderOptions component configures the rendering at each particular scene, and is usually accessed through TCastleScene.RenderOptions. This unit contains also related types, constants and some variables.

Uses

Overview

Classes, Interfaces, Objects and Records

Name Description
Class TCastleRenderOptions Options that control rendering, available at every scene through TCastleScene.RenderOptions.

Functions and Procedures

function GetGammaCorrection: TGammaCorrection; deprecated 'use ColorSpace';
procedure SetGammaCorrection(const Value: TGammaCorrection); deprecated 'use ColorSpace';

Types

TShaderType = (...);
TUniformMissing = (...);
TColorMode = (...);
TToneMapping = (...);
TColorSpace = (...);
TGammaCorrection = (...) deprecated 'use TColorSpace';
TShadersRendering = (...) deprecated 'this was only useful with TCastleRenderOptions.Shaders, which is now deprecated in favor of TCastleRenderOptions.PhongShading';
TBumpMapping = (...);
TRenderingMode = (...);
TWireframeEffect = (...);
TShadowSampling = (...);
TAutoMinificationFilter = (...);
TMinificationFilter = minNearest..minLinearMipmapLinear;
TAutoMagnificationFilter = (...);
TMagnificationFilter = magNearest..magLinear;
TBlendingSourceFactor = (...);
TBlendingDestinationFactor = (...);
TBlendingSort = (...);
T3DCoord = 0..2;
T3DCoords = set of T3DCoord;
TRenderLayer = (...);
TLineType = (...);
TCastleRenderOptionsEvent = procedure (const Options: TCastleRenderOptions) of object;
TCastleRenderOptionsClass = class of TCastleRenderOptions;

Constants

ShadowSamplingNames: array [TShadowSampling] of string = ( 'Simple', 'PCF 4', 'PCF 4 Bilinear', 'PCF 16', 'Variance Shadow Maps (Experimental)' );
ShaderTypeName: array [TShaderType] of string = ( 'Vertex', 'Geometry', 'Fragment' );
BumpMappingNames: array [TBumpMapping] of string = ( 'None', 'Basic', 'Parallax', 'Steep Parallax', 'Steep Parallax With Self-Shadowing' );
BlendingSourceFactorNames: array [TBlendingSourceFactor] of string = ( 'SRC_ALPHA', 'ONE_MINUS_SRC_ALPHA', 'ZERO', 'ONE', 'DST_COLOR', 'SRC_COLOR', 'DST_ALPHA', 'ONE_MINUS_DST_COLOR', 'ONE_MINUS_SRC_COLOR', 'ONE_MINUS_DST_ALPHA', 'SRC_ALPHA_SATURATE', 'CONSTANT_COLOR', 'ONE_MINUS_CONSTANT_COLOR', 'CONSTANT_ALPHA', 'ONE_MINUS_CONSTANT_ALPHA' );
BlendingDestinationFactorNames: array [TBlendingDestinationFactor] of string = ( 'SRC_ALPHA', 'ONE_MINUS_SRC_ALPHA', 'ZERO', 'ONE', 'DST_COLOR', 'SRC_COLOR', 'DST_ALPHA', 'ONE_MINUS_DST_COLOR', 'ONE_MINUS_SRC_COLOR', 'ONE_MINUS_DST_ALPHA', 'CONSTANT_COLOR', 'ONE_MINUS_CONSTANT_COLOR', 'CONSTANT_ALPHA', 'ONE_MINUS_CONSTANT_ALPHA' );
DefaultColorSpace = csLinearWhenPhysicalMaterial;
DefaultStencilBits = 8;

Variables

LogShadowVolumes: Boolean = false;
ColorSpace: TColorSpace = DefaultColorSpace;
ToneMapping: TToneMapping = tmNone;
InternalForceWireframe: TWireframeEffect;
property GammaCorrection: TGammaCorrection read GetGammaCorrection write SetGammaCorrection;

Description

Functions and Procedures

function GetGammaCorrection: TGammaCorrection; deprecated 'use ColorSpace';

Warning: this symbol is deprecated: use ColorSpace

This item has no description.

procedure SetGammaCorrection(const Value: TGammaCorrection); deprecated 'use ColorSpace';

Warning: this symbol is deprecated: use ColorSpace

This item has no description.

Types

TShaderType = (...);

Shader types.

Values
  • stVertex
  • stGeometry
  • stFragment
TUniformMissing = (...);

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.
TColorMode = (...);

Type of TAbstractColorNode.Mode.

Values
  • cmReplace
  • cmModulate
TToneMapping = (...);

Type of ToneMapping.

Values
TColorSpace = (...);

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
TGammaCorrection = (...) deprecated 'use TColorSpace';

Warning: this symbol is deprecated: use TColorSpace

Deprecated name for TColorSpace.

Values
  • gcNone: Never do gamma correction.
  • gcPhysicalMaterial: Gamma correction only for PhysicalMaterial.
  • gcAlways: Always do gamma correction.
TShadersRendering = (...) deprecated 'this was only useful with TCastleRenderOptions.Shaders, which is now deprecated in favor of TCastleRenderOptions.PhongShading';

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
TBumpMapping = (...);

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

Values
TRenderingMode = (...);

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.

TWireframeEffect = (...);

Values for TCastleRenderOptions.WireframeEffect.

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

Values
TShadowSampling = (...);

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.
TAutoMinificationFilter = (...);

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

Values
TMinificationFilter = minNearest..minLinearMipmapLinear;

This item has no description.

TAutoMagnificationFilter = (...);

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

Values
TMagnificationFilter = magNearest..magLinear;

This item has no description.

TBlendingSourceFactor = (...);

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
TBlendingDestinationFactor = (...);

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
TBlendingSort = (...);

Various ways to sort the objects, useful to correctly render partially-transparent objects. See https://castle-engine.io/blending .

See also
TCastleRenderOptions.BlendingSort
How to sort the rendered objects using blending (partial transparency).
TCastleAbstractRootTransform.BlendingSort
When rendering, sort all the children, making blending correct when there are multiple partially-transparent objects in the world.
Values
  • bsNone: Do not sort. This is of course fastest, but will cause artifacts if multiple partially-transparent objects may be visible on top of each other.
  • bs2D: Sort objects by their Z coordinate. Good 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 on top for 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.

  • bs3D: 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 to the camera posotion.

  • bs3DOrigin: 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 bs3D, 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.

  • bs3DGround: 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 bs3DOrigin, but the height of the object (above Y) doesn't matter.

T3DCoord = 0..2;

This item has no description.

T3DCoords = set of T3DCoord;

This item has no description.

TRenderLayer = (...);

Render layer for TCastleTransform.RenderLayer.

Values
  • rlParent
  • rlBack
  • rlFront
TLineType = (...);

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

Values
  • ltSolid
  • ltDashed
  • ltDotted
  • ltDashedDotted
  • ltDashDotDot
TCastleRenderOptionsEvent = procedure (const Options: TCastleRenderOptions) of object;

This item has no description.

TCastleRenderOptionsClass = class of TCastleRenderOptions;

This item has no description.

Constants

ShadowSamplingNames: array [TShadowSampling] of string = ( 'Simple', 'PCF 4', 'PCF 4 Bilinear', 'PCF 16', 'Variance Shadow Maps (Experimental)' );

This item has no description.

ShaderTypeName: array [TShaderType] of string = ( 'Vertex', 'Geometry', 'Fragment' );

This item has no description.

BumpMappingNames: array [TBumpMapping] of string = ( 'None', 'Basic', 'Parallax', 'Steep Parallax', 'Steep Parallax With Self-Shadowing' );

This item has no description.

BlendingSourceFactorNames: array [TBlendingSourceFactor] of string = ( 'SRC_ALPHA', 'ONE_MINUS_SRC_ALPHA', 'ZERO', 'ONE', 'DST_COLOR', 'SRC_COLOR', 'DST_ALPHA', 'ONE_MINUS_DST_COLOR', 'ONE_MINUS_SRC_COLOR', 'ONE_MINUS_DST_ALPHA', 'SRC_ALPHA_SATURATE', 'CONSTANT_COLOR', 'ONE_MINUS_CONSTANT_COLOR', 'CONSTANT_ALPHA', 'ONE_MINUS_CONSTANT_ALPHA' );

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 .

BlendingDestinationFactorNames: array [TBlendingDestinationFactor] of string = ( 'SRC_ALPHA', 'ONE_MINUS_SRC_ALPHA', 'ZERO', 'ONE', 'DST_COLOR', 'SRC_COLOR', 'DST_ALPHA', 'ONE_MINUS_DST_COLOR', 'ONE_MINUS_SRC_COLOR', 'ONE_MINUS_DST_ALPHA', 'CONSTANT_COLOR', 'ONE_MINUS_CONSTANT_COLOR', 'CONSTANT_ALPHA', 'ONE_MINUS_CONSTANT_ALPHA' );

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 .

DefaultColorSpace = csLinearWhenPhysicalMaterial;

'SRC_ALPHA_SATURATE', // NOT SUPPORTED AS DESTINATION FACTOR

DefaultStencilBits = 8;

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.

Variables

LogShadowVolumes: Boolean = false;

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

ColorSpace: TColorSpace = DefaultColorSpace;

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.

ToneMapping: TToneMapping = tmNone;

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.

)

InternalForceWireframe: TWireframeEffect;

Force given rendering for all scenes, if not weNormal.

property GammaCorrection: TGammaCorrection read GetGammaCorrection write SetGammaCorrection;

This item has no description.


Generated by PasDoc 0.16.0-snapshot.