CastleRenderOptions
type TCastleRenderOptions = class(TCastleComponent)
Options that control rendering, available at every scene through TCastleScene.RenderOptions.
nested const DefaultPointSize = 3.0;
nested const DefaultLineWidth = 2.0;
nested const DefaultBumpMapping = bmBasic;
nested const DefaultBumpMappingParallaxHeight = 0.01;
nested const DefaultPhongShading = true;
nested const DefaultMaxLightsPerShape = 64;
nested const DefaultBlendingSourceFactor = bsSrcAlpha;
nested const DefaultBlendingDestinationFactor = bdOneMinusSrcAlpha;
nested const DefaultWireframeColor: TCastleColorRGB = (X: 0; Y: 0; Z: 0);
nested const DefaultSolidWireframeScale = 1;
nested const DefaultSolidWireframeBias = 1;
nested const DefaultSilhouetteScale = 5;
nested const DefaultSilhouetteBias = 5;
nested const DefaultShadowSampling = ssPCF16;
class var DefaultMinificationFilter: TMinificationFilter;
DefaultMagnificationFilter: TMagnificationFilter;
OnCreate: TCastleRenderOptionsEvent;
procedure ReleaseCachedResources; virtual;
constructor Create(AOwner: TComponent); override;
destructor Destroy; override;
procedure Assign(Source: TPersistent); override;
procedure CustomSerialization(const SerializationProcess: TSerializationProcess); override;
function PropertySections(const PropertyName: String): TPropertySections; override;
function Equals(Obj: TObject): Boolean; override;
function EqualForShapeCache(SecondValue: TCastleRenderOptions): boolean; virtual;
property Mode: TRenderingMode read FMode write SetMode default rmFull;
property DepthTest: boolean read FDepthTest write SetDepthTest default true;
property SolidColor: TCastleColorRGB read FSolidColor write SetSolidColor;
property WireframeColor: TCastleColorRGB read FWireframeColor write SetWireframeColor;
property InternalColorChannels: TColorChannels read FColorChannels write SetColorChannels default AllColorChannels;
property Lighting: boolean read FLighting write SetLighting default true;
property ReceiveSceneLights: boolean read FReceiveSceneLights write SetReceiveSceneLights default true;
property ReceiveGlobalLights: boolean read FReceiveGlobalLights write SetReceiveGlobalLights default true;
property Textures: boolean read FTextures write SetTextures default true;
property MinificationFilter: TAutoMinificationFilter read FMinificationFilter write SetMinificationFilter default minDefault;
property MagnificationFilter: TAutoMagnificationFilter read FMagnificationFilter write SetMagnificationFilter default magDefault;
property PointSize: Single read FPointSize write SetPointSize stored IsStoredPointSize;
property LineWidth: Single read FLineWidth write SetLineWidth stored IsStoredLineWidth;
property BumpMapping: TBumpMapping read FBumpMapping write SetBumpMapping default DefaultBumpMapping;
property BumpMappingParallaxHeight: Single read FBumpMappingParallaxHeight write SetBumpMappingParallaxHeight stored IsStoredBumpMappingParallaxHeight;
property PhongShading: boolean read FPhongShading write SetPhongShading default DefaultPhongShading;
property ShadowSampling: TShadowSampling read FShadowSampling write SetShadowSampling default DefaultShadowSampling;
property MaxLightsPerShape: Cardinal read FMaxLightsPerShape write SetMaxLightsPerShape default DefaultMaxLightsPerShape;
property Blending: boolean read FBlending write SetBlending default true;
property BlendingSourceFactor: TBlendingSourceFactor read FBlendingSourceFactor write SetBlendingSourceFactor default DefaultBlendingSourceFactor;
property BlendingDestinationFactor: TBlendingDestinationFactor read FBlendingDestinationFactor write SetBlendingDestinationFactor default DefaultBlendingDestinationFactor;
property WireframeEffect: TWireframeEffect read FWireframeEffect write SetWireframeEffect default weNormal;
property SolidWireframeScale: Single read FSolidWireframeScale write SetSolidWireframeScale stored IsStoredSolidWireframeScale;
property SolidWireframeBias: Single read FSolidWireframeBias write SetSolidWireframeBias stored IsStoredSolidWireframeBias;
property SilhouetteScale: Single read FSilhouetteScale write SetSilhouetteScale stored IsStoredSilhouetteScale;
property SilhouetteBias: Single read FSilhouetteBias write SetSilhouetteBias stored IsStoredSilhouetteBias;
property RobustNegativeScale: Boolean read FRobustNegativeScale write SetRobustNegativeScale default false;
property WholeSceneManifold: Boolean read FWholeSceneManifold write SetWholeSceneManifold default false;
property WireframeColorPersistent: TCastleColorRGBPersistent read FWireframeColorPersistent ;
This item has no description.
Default value of TCastleRenderOptions.BlendingSourceFactor. This is the typical blending operation.
Default value of TCastleRenderOptions.BlendingDestinationFactor. This is the typical blending operation.
Value used when MinificationFilter is minDefault. By default, this is minLinearMipmapLinear.
Value used when MagnificationFilter is magDefault. By default, this is magLinear.
Adjust attributes of all loaded resources.
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).
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.
This item has no description. Showing description inherited from TCastleComponent.PropertySections.
Section where to show property in the editor.
Equal TCastleRenderOptions produce the same effect when rendering and can be treated as exactly equivalent by the TCastleViewport.DynamicBatching algorithm.
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.
Rendering mode, can be used to disable many rendering features at once.
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.
Color used when Mode is rmSolidColor. By default BlackRGB.
Wireframe color, used with some WireframeEffect values. Default value is DefaultWireframeColor.
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.
Enable real-time lighting when rendering.
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.
ReceiveSceneLights
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.
False
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.
ReceiveGlobalLights
Use textures.
textures
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).
Size of points. This has an effect on TPointSetNode rendering. Must be > 0.
Line width. This has an effect on TLineSetNode rendering, and on wireframe rendering when TCastleRenderOptions.WireframeEffect indicates it. Must be > 0.
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.
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.
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:
PBR materials (TPhysicalMaterialNode, in particular imported from glTF)
Using textures like normal maps, specular maps
Using shadow maps
Shadow maps sampling. Various approaches result in various quality and speed.
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.
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.
True
If this is False, everything will be rendered as opaque.
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.
BlendingSourceFactor
The typical blending setup (default) is to use
BlendingSourceFactor = DefaultBlendingSourceFactor = bsSrcAlpha.
BlendingDestinationFactor = DefaultBlendingDestinationFactor = bdOneMinusSrcAlpha.
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:
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).
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.
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.
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.
WireframeEffect
Support lighting and backface culling for models using negative scale. This has a small performance cost, and so is disabled by default.
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.
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.