Class TCastleRenderOptions

Unit

Declaration

type TCastleRenderOptions = class(TCastleComponent)

Description

Options that control rendering, available at every scene through TCastleScene.RenderOptions.

Hierarchy

Overview

Fields

Public nested const DefaultPointSize = 3.0;
Public nested const DefaultLineWidth = 2.0;
Public nested const DefaultBumpMapping = bmBasic;
Public nested const DefaultBumpMappingParallaxHeight = 0.01;
Public nested const DefaultPhongShading = true;
Public nested const DefaultMaxLightsPerShape = 64;
Public nested const DefaultBlendingSourceFactor = bsSrcAlpha;
Public nested const DefaultBlendingDestinationFactor = bdOneMinusSrcAlpha;
Public nested const DefaultWireframeColor: TCastleColorRGB = (X: 0; Y: 0; Z: 0);
Public nested const DefaultSolidWireframeScale = 1;
Public nested const DefaultSolidWireframeBias = 1;
Public nested const DefaultSilhouetteScale = 5;
Public nested const DefaultSilhouetteBias = 5;
Public nested const DefaultShadowSampling = ssPCF16;
Public class var DefaultMinificationFilter: TMinificationFilter;
Public DefaultMagnificationFilter: TMagnificationFilter;
Public OnCreate: TCastleRenderOptionsEvent;

Methods

Protected procedure ReleaseCachedResources; virtual;
Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public procedure Assign(Source: TPersistent); override;
Public procedure CustomSerialization(const SerializationProcess: TSerializationProcess); override;
Public function PropertySections(const PropertyName: String): TPropertySections; override;
Public function Equals(Obj: TObject): Boolean; override;
Public function EqualForShapeCache(SecondValue: TCastleRenderOptions): boolean; virtual;

Properties

Public property Mode: TRenderingMode read FMode write SetMode default rmFull;
Public property DepthTest: boolean read FDepthTest write SetDepthTest default true;
Public property SolidColor: TCastleColorRGB read FSolidColor write SetSolidColor;
Public property WireframeColor: TCastleColorRGB read FWireframeColor write SetWireframeColor;
Public property InternalColorChannels: TColorChannels read FColorChannels write SetColorChannels default AllColorChannels;
Published property Lighting: boolean read FLighting write SetLighting default true;
Published property ReceiveSceneLights: boolean read FReceiveSceneLights write SetReceiveSceneLights default true;
Published property ReceiveGlobalLights: boolean read FReceiveGlobalLights write SetReceiveGlobalLights default true;
Published property Textures: boolean read FTextures write SetTextures default true;
Published property MinificationFilter: TAutoMinificationFilter read FMinificationFilter write SetMinificationFilter default minDefault;
Published property MagnificationFilter: TAutoMagnificationFilter read FMagnificationFilter write SetMagnificationFilter default magDefault;
Published property PointSize: Single read FPointSize write SetPointSize stored IsStoredPointSize;
Published property LineWidth: Single read FLineWidth write SetLineWidth stored IsStoredLineWidth;
Published property BumpMapping: TBumpMapping read FBumpMapping write SetBumpMapping default DefaultBumpMapping;
Published property BumpMappingParallaxHeight: Single read FBumpMappingParallaxHeight write SetBumpMappingParallaxHeight stored IsStoredBumpMappingParallaxHeight;
Published property PhongShading: boolean read FPhongShading write SetPhongShading default DefaultPhongShading;
Published property ShadowSampling: TShadowSampling read FShadowSampling write SetShadowSampling default DefaultShadowSampling;
Published property MaxLightsPerShape: Cardinal read FMaxLightsPerShape write SetMaxLightsPerShape default DefaultMaxLightsPerShape;
Published property Blending: boolean read FBlending write SetBlending default true;
Published property BlendingSourceFactor: TBlendingSourceFactor read FBlendingSourceFactor write SetBlendingSourceFactor default DefaultBlendingSourceFactor;
Published property BlendingDestinationFactor: TBlendingDestinationFactor read FBlendingDestinationFactor write SetBlendingDestinationFactor default DefaultBlendingDestinationFactor;
Published property WireframeEffect: TWireframeEffect read FWireframeEffect write SetWireframeEffect default weNormal;
Published property SolidWireframeScale: Single read FSolidWireframeScale write SetSolidWireframeScale stored IsStoredSolidWireframeScale;
Published property SolidWireframeBias: Single read FSolidWireframeBias write SetSolidWireframeBias stored IsStoredSolidWireframeBias;
Published property SilhouetteScale: Single read FSilhouetteScale write SetSilhouetteScale stored IsStoredSilhouetteScale;
Published property SilhouetteBias: Single read FSilhouetteBias write SetSilhouetteBias stored IsStoredSilhouetteBias;
Published property RobustNegativeScale: Boolean read FRobustNegativeScale write SetRobustNegativeScale default false;
Published property WholeSceneManifold: Boolean read FWholeSceneManifold write SetWholeSceneManifold default false;
Published property WireframeColorPersistent: TCastleColorRGBPersistent read FWireframeColorPersistent ;

Description

Fields

Public nested const DefaultPointSize = 3.0;

This item has no description.

Public nested const DefaultLineWidth = 2.0;

This item has no description.

Public nested const DefaultBumpMapping = bmBasic;

This item has no description.

Public nested const DefaultBumpMappingParallaxHeight = 0.01;

This item has no description.

Public nested const DefaultPhongShading = true;

This item has no description.

Public nested const DefaultMaxLightsPerShape = 64;

This item has no description.

Public nested const DefaultBlendingSourceFactor = bsSrcAlpha;

Default value of TCastleRenderOptions.BlendingSourceFactor. This is the typical blending operation.

Public nested const DefaultBlendingDestinationFactor = bdOneMinusSrcAlpha;

Default value of TCastleRenderOptions.BlendingDestinationFactor. This is the typical blending operation.

Public nested const DefaultWireframeColor: TCastleColorRGB = (X: 0; Y: 0; Z: 0);

This item has no description.

Public nested const DefaultSolidWireframeScale = 1;

This item has no description.

Public nested const DefaultSolidWireframeBias = 1;

This item has no description.

Public nested const DefaultSilhouetteScale = 5;

This item has no description.

Public nested const DefaultSilhouetteBias = 5;

This item has no description.

Public nested const DefaultShadowSampling = ssPCF16;

This item has no description.

Public class var DefaultMinificationFilter: TMinificationFilter;

Value used when MinificationFilter is minDefault. By default, this is minLinearMipmapLinear.

Public DefaultMagnificationFilter: TMagnificationFilter;

Value used when MagnificationFilter is magDefault. By default, this is magLinear.

Public OnCreate: TCastleRenderOptionsEvent;

Adjust attributes of all loaded resources.

Methods

Protected procedure ReleaseCachedResources; virtual;

Called before changing an attribute that requires the release of things cached in a renderer. This includes attributes that affect:

  • How TShapeCache.Arrays contents are generated. For example, Generator uses TexCoordsNeeded, so changing any attribute that affects TexCoordsNeeded calls this method.

  • How (and if) TShapeCache.Vbo are loaded.

  • How textures are loaded (texture filtering options affect them).

Public constructor Create(AOwner: TComponent); override;

This item has no description.

Public destructor Destroy; override;

This item has no description.

Public procedure Assign(Source: TPersistent); override;

This item has no description.

Public procedure CustomSerialization(const SerializationProcess: TSerializationProcess); override;

This item has no description. Showing description inherited from TCastleComponent.CustomSerialization.

Override this method to call various methods of SerializationProcess, which in turn allows to serialize/deserialize things that are not published. This allows to serialize/deserialize with more freedom, e.g. to serialize/deserialize some private field.

Public function PropertySections(const PropertyName: String): TPropertySections; override;

This item has no description. Showing description inherited from TCastleComponent.PropertySections.

Section where to show property in the editor.

Public function Equals(Obj: TObject): Boolean; override;

Equal TCastleRenderOptions produce the same effect when rendering and can be treated as exactly equivalent by the TCastleViewport.DynamicBatching algorithm.

Public function EqualForShapeCache(SecondValue: TCastleRenderOptions): boolean; virtual;

Is the second TCastleRenderOptions instance on all fields that affect TShapeCache, that is things that affect generated geometry arrays or vbo. This compares the subset of variables that call ReleaseCachedResources — only the ones that affect TShapeCache.

Properties

Public property Mode: TRenderingMode read FMode write SetMode default rmFull;

Rendering mode, can be used to disable many rendering features at once.

Public property DepthTest: boolean read FDepthTest write SetDepthTest default true;

By default, we use depth testing to determine which objects are in front of the others. This allows to display all 3D content (all TCastleScene instances, and all shapes inside them) in any order.

For very special purposes, you can disable depth testing. This means that 3D objects will always be drawn in front of the previous ones, in the order in which they are rendered, ignoring the contents of the depth buffer. Use only if you know what you're doing, if you're sure that the order of rendering will always be good.

Public property SolidColor: TCastleColorRGB read FSolidColor write SetSolidColor;

Color used when Mode is rmSolidColor. By default BlackRGB.

Public property WireframeColor: TCastleColorRGB read FWireframeColor write SetWireframeColor;

Wireframe color, used with some WireframeEffect values. Default value is DefaultWireframeColor.

Public property InternalColorChannels: TColorChannels read FColorChannels write SetColorChannels default AllColorChannels;

Which color buffer channels (RGBA) to write when rendering this model.

This makes a cool effect, avoiding writing to some color channels, but writing others, and writing depth buffer. This property may change to be non-internal some day, please report on Castle Game Engine forum / Discord / GitHub ( https://castle-engine.io/talk.php ) if you find it useful.

Published property Lighting: boolean read FLighting write SetLighting default true;

Enable real-time lighting when rendering.

Published property ReceiveSceneLights: boolean read FReceiveSceneLights write SetReceiveSceneLights default true;

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.

Published property ReceiveGlobalLights: boolean read FReceiveGlobalLights write SetReceiveGlobalLights default true;

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.

Published property Textures: boolean read FTextures write SetTextures default true;

Use textures.

Published property MinificationFilter: TAutoMinificationFilter read FMinificationFilter write SetMinificationFilter default minDefault;

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).

Published property MagnificationFilter: TAutoMagnificationFilter read FMagnificationFilter write SetMagnificationFilter default magDefault;

This item has no description.

Published property PointSize: Single read FPointSize write SetPointSize stored IsStoredPointSize;

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

Published property LineWidth: Single read FLineWidth write SetLineWidth stored IsStoredLineWidth;

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

Published property BumpMapping: TBumpMapping read FBumpMapping write SetBumpMapping default DefaultBumpMapping;

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.

Published property BumpMappingParallaxHeight: Single read FBumpMappingParallaxHeight write SetBumpMappingParallaxHeight stored IsStoredBumpMappingParallaxHeight;

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.

Published property PhongShading: boolean read FPhongShading write SetPhongShading default DefaultPhongShading;

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:

Published property ShadowSampling: TShadowSampling read FShadowSampling write SetShadowSampling default DefaultShadowSampling;

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

Published property MaxLightsPerShape: Cardinal read FMaxLightsPerShape write SetMaxLightsPerShape default DefaultMaxLightsPerShape;

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.

Published property Blending: boolean read FBlending write SetBlending default true;

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.

Published property BlendingSourceFactor: TBlendingSourceFactor read FBlendingSourceFactor write SetBlendingSourceFactor default DefaultBlendingSourceFactor;

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

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.

Published property BlendingDestinationFactor: TBlendingDestinationFactor read FBlendingDestinationFactor write SetBlendingDestinationFactor default DefaultBlendingDestinationFactor;

This item has no description.

Published property WireframeEffect: TWireframeEffect read FWireframeEffect write SetWireframeEffect default weNormal;

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.

Published property SolidWireframeScale: Single read FSolidWireframeScale write SetSolidWireframeScale stored IsStoredSolidWireframeScale;

This item has no description.

Published property SolidWireframeBias: Single read FSolidWireframeBias write SetSolidWireframeBias stored IsStoredSolidWireframeBias;

This item has no description.

Published property SilhouetteScale: Single read FSilhouetteScale write SetSilhouetteScale stored IsStoredSilhouetteScale;

This item has no description.

Published property SilhouetteBias: Single read FSilhouetteBias write SetSilhouetteBias stored IsStoredSilhouetteBias;

This item has no description.

Published property RobustNegativeScale: Boolean read FRobustNegativeScale write SetRobustNegativeScale default false;

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

Published property WholeSceneManifold: Boolean read FWholeSceneManifold write SetWholeSceneManifold default false;

When considering this scene to be a shadow caster for shadow volumes, assume it is 2-manifold when treated as whole scene (each separate shape may be not 2-manifold). This means that you guarantee that all border edges of all shapes match with each other, closing the skin of the model perfectly. See https://castle-engine.io/shadow_volumes about using shadow volumes and the requirement to be 2-manifold.

If this is True then, even if some shapes are not 2-manifold, we will generate shadow (using shadow volumes) from them. And we will never reject shadows from a particular shape, we will either reject whole scene shadow, or render whole scene shadow.

It is the user responsibility to guarantee that whole scene is really 2-manifold. If it is not, then shadow volumes may exhibit weird artifacts.

Published property WireframeColorPersistent: TCastleColorRGBPersistent read FWireframeColorPersistent ;

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.

Generated by PasDoc 0.16.0-snapshot.