Class TCastleMask

Unit

Declaration

type TCastleMask = class(TCastleUserInterface)

Description

Limit the visibility of children by an arbitrary (defined using an arbitrary UI) mask.

The children controls are visible only where the Mask is rendered, or where the mask is not rendered. You can customize the mask effect using MaskRendering.

Limitation of the current implementation: You cannot have other controls underneath TCastleMask (inside Mask or inside other children) that deal with stencil buffer. In practice, it means that you cannot use TCastleMask within another TCastleMask, and you cannot use TCastleViewport with shadow volumes within TCastleMask. Set TCastleViewport.ShadowVolumes to False to make TCastleViewport reliable inside a TCastleMask. TODO: This limitation may be removed one day, it's possible by using distinct stencil buffer bits (masks).

Hierarchy

Overview

Methods

Protected procedure InternalRenderLoop(const ViewportRect: TRectangle); override;
Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public function PropertySections(const PropertyName: String): TPropertySections; override;

Properties

Published property Mask: TCastleUserInterface read FMask;
Published property MaskRendering: TMaskRendering read FMaskRendering write SetMaskRendering default mrChildrenWhereNoMask;

Description

Methods

Protected procedure InternalRenderLoop(const ViewportRect: TRectangle); override;

This item has no description.

Public constructor Create(AOwner: TComponent); override;

This item has no description.

Public destructor Destroy; override;

This item has no description.

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.

Properties

Published property Mask: TCastleUserInterface read FMask;

Place in Mask any UI control (TCastleUserInterface) to limit where the children are rendered.

The colors of the mask UI don't matter, but the pixels that are touched by the mask matter. So you can e.g. define a mask using an image (TCastleImageControl), make sure to set TCastleImageControl.AlphaChannel to acTest to make the mask apply where the image is opaque. Or you can define a mask using a viewport with 2D or 3D scenes – TCastleViewport, with TCastleViewport.Transparent. Or you can define a mask using a shape, like TCastleRectangleControl or TCastleShape.

The Mask is a subcomponent with TCastleUserInterface.FullSize = True by default, so it fills the entire TCastleMask by default.

The children in Mask are never rendered to the color or depth buffers (unless MaskRendering is mrMask). They are only rendered to set the stencil buffer.

Published property MaskRendering: TMaskRendering read FMaskRendering write SetMaskRendering default mrChildrenWhereNoMask;

How children of this control are limited by the mask.

  • mrChildrenWhereNoMask (default):

    Children are rendered only where mask is not visible.

    This is the default, and it means that when mask is empty (also the default state) then the children are rendered as usual.

  • mrChildrenWhereMask:

    Children are rendered only where mask is visible.

  • mrChildrenIgnoreMask:

    Turns off mask usage, effectively making TCastleMask a regular UI control and the contents of Mask meaningless.

  • mrMask:

    Render only mask, as a regular UI control. Other children are not rendered. This mode is useful to design mask at design-time, where it may be easier to just see mask UI explicitly.

Note that mrChildrenWhereNoMask and mrChildrenWhereMask values only work when there is a stencil buffer available. If the stencil buffer is not available, they behave as if MaskRendering = mrChildrenIgnoreMask, so the mask will not do anything. All modern GPUs provide a stencil buffer, and CGE requests stencil buffer by default. Check GLFeatures.StencilBits <> 0 if you want to react to lack of stencil buffer in some particular way in your code.


Generated by PasDoc 0.16.0-snapshot.