Class TCastleRenderOptions

Unit

Declaration

type TCastleRenderOptions = class(TComponent)

Description

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

Hierarchy

  • TObject
  • TPersistent
  • TComponent
  • TCastleRenderOptions

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 DefaultBlendingSort = bs3D;
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 function EqualForShapeCache(SecondValue: TCastleRenderOptions): boolean; virtual;

Properties

Public property Shaders: TShadersRendering read GetShaders write SetShaders; deprecated 'use PhongShading';
Public property Mode: TRenderingMode read FMode write SetMode default rmFull;
Public property VisualizeDepthMap: boolean read FVisualizeDepthMap write SetVisualizeDepthMap default false;
Public property DepthTest: boolean read FDepthTest write FDepthTest default true;
Public property SolidColor: TCastleColorRGB read FSolidColor write FSolidColor;
Public property SolidColorBlendingPipeline: Boolean read FSolidColorBlendingPipeline write FSolidColorBlendingPipeline;
Public property WireframeColor: TCastleColorRGB read FWireframeColor write FWireframeColor;
Public property DebugHierOcclusionQueryResults: boolean read FDebugHierOcclusionQueryResults write FDebugHierOcclusionQueryResults default false;
Published property Lighting: boolean read FLighting write FLighting default true;
Published property ReceiveSceneLights: boolean read FReceiveSceneLights write FReceiveSceneLights default true;
Published property ReceiveGlobalLights: boolean read FReceiveGlobalLights write FReceiveGlobalLights 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 FPointSize default DefaultPointSize;
Published property LineWidth: Single read FLineWidth write FLineWidth default DefaultLineWidth;
Published property BumpMapping: TBumpMapping read FBumpMapping write SetBumpMapping default DefaultBumpMapping;
Published property BumpMappingParallaxHeight: Single read FBumpMappingParallaxHeight write FBumpMappingParallaxHeight default DefaultBumpMappingParallaxHeight;
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 FMaxLightsPerShape 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 BlendingSort: TBlendingSort read FBlendingSort write SetBlendingSort default DefaultBlendingSort;
Published property OcclusionSort: boolean read FOcclusionSort write FOcclusionSort default false;
Published property WireframeEffect: TWireframeEffect read FWireframeEffect write FWireframeEffect default weNormal;
Published property SolidWireframeScale: Single read FSolidWireframeScale write FSolidWireframeScale default DefaultSolidWireframeScale;
Published property SolidWireframeBias: Single read FSolidWireframeBias write FSolidWireframeBias default DefaultSolidWireframeBias;
Published property SilhouetteScale: Single read FSilhouetteScale write FSilhouetteScale default DefaultSilhouetteScale;
Published property SilhouetteBias: Single read FSilhouetteBias write FSilhouetteBias default DefaultSilhouetteBias;
Published property OcclusionQuery: boolean read FOcclusionQuery write SetOcclusionQuery default false;
Published property RobustNegativeScale: Boolean read FRobustNegativeScale write FRobustNegativeScale default false;
Published property WireframeColorPersistent: TCastleColorRGBPersistent read FWireframeColorPersistent ;

Description

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;

Default value of Attributes.BlendingDestinationFactor. See TCastleRenderOptions.BlendingDestinationFactor.

Using bdOneMinusSrcAlpha is the standard value for 3D graphic stuff, often producing best results. However, it causes troubles when multiple transparent shapes are visible on the same screen pixel. For closed convex 3D objects, using backface culling (solid = TRUE for geometry) helps. For multiple transparent shapes, sorting the transparent shapes helps, see TCastleRenderOptions.BlendingSort. Sometimes, no solution works for all camera angles.

Another disadvantage of bdOneMinusSrcAlpha may be that the color of opaque shapes disappears too quickly from resulting image (since bdOneMinusSrcAlpha scales it down). So the image may be darker than you like.

You can instead consider using bdOne, that doesn't require sorting and never has problems with multiple transparent shapes. On the other hand, it only adds to the color, often making too bright results.

Public nested const DefaultBlendingSort = bs3D;

Default value of TCastleRenderOptions.BlendingSort.

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;

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;
 
Public destructor Destroy; override;
 
Public procedure Assign(Source: TPersistent); override;
 
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 Shaders: TShadersRendering read GetShaders write SetShaders; deprecated 'use PhongShading';

Warning: this symbol is deprecated: use PhongShading

When GLSL shaders are used. This is now a deprecated property, better use PhongShading to determine the shading. The engine auto-detects whether to use shaders based on OpenGL capabilities, particular shape needs (phong shading, bump mapping, shadow maps, compositing shader effects), and GLFeatures.EnableFixedFunction.

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

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

Public property VisualizeDepthMap: boolean read FVisualizeDepthMap write SetVisualizeDepthMap default false;

Visualize depths stored in the shadow maps, instead of using them to actually make shadow.

Even without turning this on, VRML author can always activate it explicitly for specific lights. For this, you have to use X3DLightNode.defaultShadowMap field, and place a GeneratedShadowMap node there. If the GeneratedShadowMap.compareMode is set to 'NONE', we will always visualize depths of this shadow map.

Setting this property to True has the same effect as setting compareMode to "NONE" on all (explicit and implicitly created) GeneratedShadowMap nodes.

Public property DepthTest: boolean read FDepthTest write FDepthTest 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 FSolidColor;

Color used when Mode is rmSolidColor.

Public property SolidColorBlendingPipeline: Boolean read FSolidColorBlendingPipeline write FSolidColorBlendingPipeline;

Whether to render shapes as transparent, when Mode is rmSolidColor.

Public property WireframeColor: TCastleColorRGB read FWireframeColor write FWireframeColor;

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

Public property DebugHierOcclusionQueryResults: boolean read FDebugHierOcclusionQueryResults write FDebugHierOcclusionQueryResults default false;

View only the shapes that were detected as visible by occlusion query in last Render.

Use this only after render with HierarchicalOcclusionQuery. TODO: for OcclusionQuery I would also like to make it work, for now not done as frustum information is gone. This will disable actual occlusion query, instead reusing results from last occlusion query done when this debug flag was False.

Useful to quickly visualize the benefits of occlusion query.

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

Enable real-time lighting when rendering.

Published property ReceiveSceneLights: boolean read FReceiveSceneLights write FReceiveSceneLights 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 FReceiveGlobalLights 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;
 
Published property PointSize: Single read FPointSize write FPointSize default DefaultPointSize;

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

Published property LineWidth: Single read FLineWidth write FLineWidth default DefaultLineWidth;

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 FBumpMappingParallaxHeight default DefaultBumpMappingParallaxHeight;

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 FMaxLightsPerShape 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. Note that this is only a default, each model can override this for specific shapes using TBlendModeNode. See https://castle-engine.io/x3d_extensions.php#section_ext_blending for details of TBlendModeNode.

See https://castle-engine.io/blending for details how it works.

Published property BlendingDestinationFactor: TBlendingDestinationFactor read FBlendingDestinationFactor write SetBlendingDestinationFactor default DefaultBlendingDestinationFactor;
 
Published property BlendingSort: TBlendingSort read FBlendingSort write SetBlendingSort default DefaultBlendingSort;

How to sort the rendered objects using blending (partial transparency). See the TBlendingSort documentation for possible values.

This may be overridden in a specific 3D models by using NavigationInfo node with blendingSort field, see TNavigationInfoNode.BlendingSort.

Published property OcclusionSort: boolean read FOcclusionSort write FOcclusionSort default false;

Sort the opaque objects when rendering. This may generate speedup on some scenes.

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

You can use this to turn on some effects related to rendering model in special modes.

When this is weNormal (default), nothing special is done, which means that model polygons are simply passed to OpenGL. Whether this results in filled or wireframe, depends on OpenGL glPolygonMode setting, filled by default.

How the wireframe effects work when Mode = rmDepth is undefined now. Just don't use Mode = rmDepth if you're unsure.

See description of TWireframeEffect for what other modes do.

Published property SolidWireframeScale: Single read FSolidWireframeScale write FSolidWireframeScale default DefaultSolidWireframeScale;
 
Published property SolidWireframeBias: Single read FSolidWireframeBias write FSolidWireframeBias default DefaultSolidWireframeBias;
 
Published property SilhouetteScale: Single read FSilhouetteScale write FSilhouetteScale default DefaultSilhouetteScale;
 
Published property SilhouetteBias: Single read FSilhouetteBias write FSilhouetteBias default DefaultSilhouetteBias;
 
Published property OcclusionQuery: boolean read FOcclusionQuery write SetOcclusionQuery default false;

Use the occlusion query to optimize the rendering. The shapes obscured by other shapes will not be rendered. This makes sense when in your view, many shapes are typically obscured by others.

See the https://castle-engine.io/occlusion_query for details how does this work.

This is ignored if HierarchicalOcclusionQuery.

This is ignored if GPU doesn't support the necessary functionality (for OpenGL, we require ARB_occlusion_query).

Published property RobustNegativeScale: Boolean read FRobustNegativeScale write FRobustNegativeScale 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 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.