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 = bmSteepParallaxShadowing;
Public nested const DefaultPhongShading = false;
Public nested const DefaultMaxLightsPerShape = 8;
Public nested const DefaultBlendingSourceFactor = bsSrcAlpha;
Public nested const DefaultBlendingDestinationFactor = bdOneMinusSrcAlpha;
Public nested const DefaultBlendingSort = bs3D;
Public nested const DefaultWireframeColor: TCastleColorRGB = (Data: (0, 0, 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 CustomShader: TObject read FCustomShader write FCustomShader; deprecated 'use Effect node to define GLSL shaders that are more flexible';
Public property CustomShaderAlphaTest: TObject read FCustomShaderAlphaTest write FCustomShaderAlphaTest; deprecated 'use Effect node to define GLSL shaders that are more flexible';
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 SceneLights: boolean read FSceneLights write FSceneLights 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 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 WireframeColorPersistent: TCastleColorRGBPersistent read FWireframeColorPersistent ;

Description

Fields

Public nested const DefaultPointSize = 3.0;
 
Public nested const DefaultLineWidth = 2.0;
 
Public nested const DefaultBumpMapping = bmSteepParallaxShadowing;
 
Public nested const DefaultPhongShading = false;
 
Public nested const DefaultMaxLightsPerShape = 8;
 
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 = (Data: (0, 0, 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 CustomShader: TObject read FCustomShader write FCustomShader; deprecated 'use Effect node to define GLSL shaders that are more flexible';

Warning: this symbol is deprecated: use Effect node to define GLSL shaders that are more flexible

Custom GLSL shader to use for the whole scene. It must be a TX3DShaderProgramBase instance. When this is assigned, Shaders value is ignored.

Avoid using this. It's not easy to create portable shaders, that work both with OpenGL and OpenGLES. Try using "compositing shaders" instead https://castle-engine.io/compositing_shaders.php which still allow you to write GLSL effects, but they are integrated into standard shader code.

Public property CustomShaderAlphaTest: TObject read FCustomShaderAlphaTest write FCustomShaderAlphaTest; deprecated 'use Effect node to define GLSL shaders that are more flexible';

Warning: this symbol is deprecated: use Effect node to define GLSL shaders that are more flexible

Alternative custom GLSL shader used when alpha test is necessary. It must be a TX3DShaderProgramBase instance. Relevant only if CustomShader <> nil.

Do not use this. This is a temporary hack to enable VSM working with alpha test. It's not clean, and should not be used for anything else.

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 SceneLights: boolean read FSceneLights write FSceneLights default true;

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

If false, only the headlight (depending on Viewport.Items.UseHeadlight) and global lights from Viewport.Items.MainScene (depending on TCastleRootTransform.UseGlobalLights) affect this scene.

This doesn't matter if Lighting is False.

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

The normal map is usually provided in the TMaterialNode.NormalTexture (Phong lighting) or TPhysicalMaterialNode.NormalTexture (PBR lighting) fields. In CGE we also provide a number of alternative ways to provide normal maps ( https://castle-engine.io/x3d_implementation_texturing_extensions.php ), but the NormalTexture field is most advised.

See TBumpMapping for various possible values.

Simple bump mapping (when only normal map is available) means that normals are provided in the texture, and lighting is calculated per-fragment.

Parallax bump mapping means that additionally the texture coordinate is perturbed, based on 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. And self-shadowing means that these bricks even cast appropriate shadows on each other.

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.

Note that, instead of increasing this limit, you can sometimes adjust your models to fit within this limit. Do this using 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://github.com/castle-engine/castle-engine/wiki/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://github.com/castle-engine/castle-engine/wiki/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;

Should we use ARB_occlusion_query (if available) to avoid rendering shapes that didn't pass occlusion test in previous frame. Ignored if GPU doesn't support ARB_occlusion_query.

True may give you a large speedup in some scenes. OTOH, a lag of one frame may happen between an object should be rendered and it actually appears.

When you render more than once the same instance of TCastleScene scene, you should not activate it (as the occlusion query doesn't make sense if each following render of the scene takes place at totally different translation). Also, when rendering something more than just one TCastleScene scene (maybe many times the same TCastleScene instance, maybe many different TCastleScene instances, maybe some other 3D objects) you should try to sort rendering order from the most to the least possible occluder (otherwise occlusion query will not be as efficient at culling).

This is ignored if HierarchicalOcclusionQuery.

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