Gorilla.Controller.Passes.Environment

Overview

This unit renders the scene into a cube map from a chosen point in space. The resulting environment texture is used for dynamic reflections, image-based lighting and environment mapping on materials — instead of a static skybox image, the cube map is generated from the live scene.

Architecture

The environment pass is a pre-pass using RenderListToFBO with 6 iterations, one per cube map face. An internal camera (90° field of view, 1:1 aspect) is reoriented for each face, and the six faces are rendered into a TGorillaCubeMapTextureBitmap render target with mip-maps. An optional embedded point light can illuminate the capture.

Core Classes

TGorillaRenderPassEnvironment

Inherits from: TGorillaRenderPassController

Default pass id: 'Environment'

Published Properties

Property Type Default Description
Position TPosition3D (0, 0, 0) World-space point from which the environment is captured.
IsDynamic Boolean False True re-renders the cube map every cycle; False renders once (static).
Target TControl3D nil Optional object the environment capture is linked to.
UseEmbeddedLight Boolean True Enables the built-in point light used during capture.
CenterOffsetFront Single 0 Render-point offset for the +Z (front) face.
CenterOffsetBack Single 0 Render-point offset for the −Z (back) face.
CenterOffsetLeft Single 0 Render-point offset for the −X (left) face.
CenterOffsetRight Single 0 Render-point offset for the +X (right) face.
CenterOffsetTop Single 0 Render-point offset for the +Y (top) face.
CenterOffsetBottom Single 0 Render-point offset for the −Y (bottom) face.

Public Properties

Property Type Default Description
Camera TCamera — Internal cube map camera (angle of view forced to 90°).
EmbeddedLight TLight — Built-in point light used to support the capture.
MapSize Integer 128 Quadratic cube map face size. Use powers of two (16, 32, 64, 128, 256, 512, 1024).
CubeMap TTextureBitmap — The underlying TGorillaCubeMapTextureBitmap.
BiasMatrix TMatrix3D — Read-only texture bias matrix.

Key Public Methods

function GetOutputTexture() : TTexture; override;
function GetViewMatrix(const AContext : TContext3D) : TMatrix3D; override;
function GetProjectionMatrix(const AContext : TContext3D) : TMatrix3D; override;
procedure SetupMatrices(const AContext : TContext3D);
function GetTextureMatrix(AContext : TContext3D;
  const AUseBias : Boolean = true) : TMatrix3D; override;

procedure InvalidateEnvironment();
procedure SetCenterOffsets(AFront, ABack, ALeft, ARight, ATop, ABottom : Single); overload;
procedure SetCenterOffsets(AOffset : Single); overload;

InvalidateEnvironment() forces a refresh of a static capture; it is called automatically when Position changes.

CreateMaterialSource() returns nil — objects are rendered with their original materials.

Runtime Setup

uses
  Gorilla.Controller.Passes.Environment;

var
  LEnv: TGorillaRenderPassEnvironment;
begin
  LEnv := TGorillaRenderPassEnvironment.Create(nil);
  LEnv.Viewport  := GorillaViewport1;
  LEnv.Position  := Point3D(0, 2, 0);   // capture point
  LEnv.MapSize   := 256;
  LEnv.IsDynamic := True;               // refresh every frame

  // Don't capture the reflective object itself
  LEnv.IgnoreControl(ReflectiveSphere);

  LEnv.Enabled := True;
end;

Assign the pass to a material's EnvironmentPass property (see Materials → Environment Mapping).

Technical Details

  • Pass type: Pre-pass (TRenderPassType.Pre)
  • Render method: RenderListToFBO, 6 iterations (one per cube map face)
  • Render procedure: DefaultRendering
  • Output texture: TGorillaTextureKind.CubeMap, style [RenderTarget, MipMaps], 9 mip-map levels, Linear filtering. Mip-maps are generated at the end of the capture.
  • Projection: perspective, 1:1 aspect, 90° FOV, near 0.1, far 1000.
  • Set IsDynamic := False for static environments (e.g. fixed rooms) to capture only once and save performance; use InvalidateEnvironment() when the scene changes.
  • Per-face CenterOffset* values let you bias the capture point per direction to reduce parallax errors for non-spherical reflectors.

See Also