Class TCastleScreenEffects

Unit

Declaration

type TCastleScreenEffects = class(TUIControlSizeable)

Description

Control that applies shader screen effects (post-processing) on the rendering done by children and (when this class is used as an ancestor) it's descendants.

It can be used to apply screen effects over any UI control, like TCastleSceneManager, TCastleViewport, TCastleButton, TCastleImageControl and so on. Simply place the desired control as child of this control.

To make it easier to apply effects on TCastleSceneManager and TCastleViewport, they already descend from this class. So, while you can, you don't need to wrap TCastleSceneManager instance inside another TCastleScreenEffects instance. You can instead directly call AddScreenEffect on your TCastleSceneManager instance.

Note that the UI controls rendered for the screen effects (our children and descendants) must always initialize and fill colors of the entire rectangle (ScreenRect) of this control. Otherwise, the results are undefined, as an internal texture that is used for screen effects is initially undefined. You may use e.g. TCastleSimpleBackground or TCastleRectangle or TCastleSceneManager with TCastleSceneManager.Background:=true to always reliably fill the background.

Hierarchy

Overview

Methods

Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public procedure AddScreenEffect(const Node: TAbstractChildNode);
Public procedure RemoveScreenEffect(const Node: TAbstractChildNode);
Public procedure BeforeRender; override;
Public procedure Render; override;
Public procedure RenderOverChildren; override;
Public procedure Update(const SecondsPassed: Single; var HandleInput: boolean); override;
Public procedure GLContextClose; override;
Public procedure PrepareResources;

Properties

Public property ScreenEffectsTimeScale: Single read FScreenEffectsTimeScale write FScreenEffectsTimeScale default 1;

Description

Methods

Public constructor Create(AOwner: TComponent); override;
 
Public destructor Destroy; override;
 
Public procedure AddScreenEffect(const Node: TAbstractChildNode);

Add or remove a ScreenEffect node that defines new shader screen effect. See https://castle-engine.io/x3d_extensions_screen_effects.php .

In the simple case, you can pass here an instance of TScreenEffectNode. In a general case, you can passs here any X3D node you want, just remember that only the TScreenEffectNode inside will be rendered. You can e.g. pass a TGroupNode with TScreenEffectNode and TTimeSensorNode as children, and use TTimeSensorNode to provide time to your shader uniform parameter. Or you can e.g. pass an X3D graph loaded from X3D file using X3DLoad.Load3D, this way you can define effects inside an external X3D file, e.g. like this:

SceneManager.AddScreenEffect(
  Load3D(ApplicationData('screen_effects_scene.x3dv')));

If you're looking for inspirations what to put in screen_effects_scene.x3dv, see https://github.com/castle-engine/demo-models/tree/master/screen_effects . See also CGE example in "examples/screen_effects_demo/" directory ( https://github.com/castle-engine/castle-engine/tree/master/examples/screen_effects_demo ) that shows more screen effects code, and shows how to load or construct X3D node graph with ScreenEffect.

The memory management of the node added here is automatic: the added screen effect becomes owned by the internal X3D Group node. It's reference-count is increased at AddScreenEffect, and decreased at RemoveScreenEffect, and it is automatically freed when reference-count drops to zero.

This means that, if you create the provided Node by code, and don't add it anywhere else, then the node will be freed automatically at our destructor (if you call AddScreenEffect and do not call RemoveScreenEffect on it), or at RemoveScreenEffect call. If you don't want this, use TX3DNode.KeepExistingBegin to manage the node destruction yourself.

Note that the given Node should not be used by other TCastlScene instances. In general, a node should not be present in more than one TCastlScene instance, and we already insert the node into an internal TCastlScene instance. Use TX3DNode.DeepCopy if necessary to duplicate node into multiple scenes.

Note that you can enable/disable the effect using TScreenEffectNode.Enabled, you do not need to remove the node only to disable it.

Public procedure RemoveScreenEffect(const Node: TAbstractChildNode);
 
Public procedure BeforeRender; override;
 
Public procedure Render; override;
 
Public procedure RenderOverChildren; override;
 
Public procedure Update(const SecondsPassed: Single; var HandleInput: boolean); override;
 
Public procedure GLContextClose; override;
 
Public procedure PrepareResources;

Make the screen effects rendering resources ready (e.g. link shaders).

Properties

Public property ScreenEffectsTimeScale: Single read FScreenEffectsTimeScale write FScreenEffectsTimeScale default 1;

Scale time passing inside TimeSensor nodes you add as part of AddScreenEffect. May be 0 to stop time passing. This has deliberately long name, instead of simple TimeScale, to make it clear that it's completely independent from TCastleSceneManager.TimeScale.


Generated by PasDoc 0.15.0.