Castle Game Engine

Class TRenderContext

Description
Hierarchy
Fields
Methods
Properties

Unit

CastleRenderContext

Declaration

type TRenderContext = class(TObject)

Description

The OpenGL / OpenGLES context state. We try hard to make this a very, very small class, because usually it's better to introduce a clean higher-level API than to track the OpenGL context state in a simple global RenderContext instance.

Use the methods and properties of this class only when this context is current, which means it's set as RenderContext value.

Do not depend on the context state being persistent. The RenderContext does not change during a single TCastleUserInterface.OnRender method (with all 2D and 3D stuff rendered inside), but that's all we guarantee. On desktops, you control the context creation / destruction explicitly (by opening / closing the TCastleWindow). But on mobile devices – the context may get destroyed and created at almost any moment. So do not use the instance of RenderContext to store anything you rely on being stored. Instead, use your own variables for this, and only synchronize RenderContext with your variables.

Hierarchy

Overview

Methods

Public constructor Create;
Public destructor Destroy; override;
Public procedure Clear(const Buffers: TClearBuffers; const ClearColor: TCastleColor);
Public procedure ScissorEnable(const Rect: TRectangle);
Public procedure ScissorDisable;
Public function FinalScissor(out Rect: TRectangle): Boolean;

Properties

Public property LineWidth: Single read FLineWidth write SetLineWidth default 1;
Public property PointSize: Single read FPointSize write SetPointSize default 1;
Public property GlobalAmbient: TCastleColorRGB read FGlobalAmbient write SetGlobalAmbient;
Public property ProjectionMatrix: TMatrix4 read FProjectionMatrix write SetProjectionMatrix;
Public property DepthRange: TDepthRange read FDepthRange write SetDepthRange;
Public property CullFace: boolean read FCullFace write SetCullFace default false;
Public property FrontFaceCcw: boolean read FFrontFaceCcw write SetFrontFaceCcw default true;
Public property ColorMask: boolean read GetColorMask write SetColorMask default true; deprecated 'use ColorChannels';
Public property ColorChannels: TColorChannels read FColorChannels write SetColorChannels default [0..3];
Public property DepthBufferUpdate: Boolean read FDepthBufferUpdate write SetDepthBufferUpdate default true;
Public property Viewport: TRectangle read FViewport write SetViewport;
Public property ViewportDelta: TVector2Integer read FViewportDelta write SetViewportDelta;
Public property CurrentProgram: TGLSLProgram read FCurrentProgram write SetCurrentProgram;

Description

Methods

Public constructor Create;
 
Public destructor Destroy; override;
 
Public procedure Clear(const Buffers: TClearBuffers; const ClearColor: TCastleColor);

Clear the whole buffer contents.

Never call OpenGL glClear or glClearColor, always use this method.

Public procedure ScissorEnable(const Rect: TRectangle);

Enable or disable scissor.

Never call OpenGL glScissor or glEnable(GL_SCISSOR_TEST) / glDisable(GL_SCISSOR_TEST) directly, or push/pop the related attrib (in case of fixed-function pipeline).

Public procedure ScissorDisable;
 
Public function FinalScissor(out Rect: TRectangle): Boolean;

Scissor rectangle to which we clip the view. This is determined by all TScissor that are currently enabled. Returns True and sets Rect if any scissor is active. Returns False if we don't clip the view now.

Properties

Public property LineWidth: Single read FLineWidth write SetLineWidth default 1;

The rendered line width. Never call OpenGL glLineWidth directly.

Do not access this property directly, unless you make direct OpenGL/OpenGLES calls. In normal circumstances, engine API (like DrawPrimitive2D or TCastleScene) set this automatically.

Public property PointSize: Single read FPointSize write SetPointSize default 1;

The rendered point size. Never call OpenGL glPointSize directly.

Do not access this property directly, unless you make direct OpenGL/OpenGLES calls. In normal circumstances, engine API (like DrawPrimitive2D or TCastleScene) set this automatically.

Public property GlobalAmbient: TCastleColorRGB read FGlobalAmbient write SetGlobalAmbient;

Global ambient lighting. This is added to every 3D object color, multiplied by material ambient.

The default value is (0.2, 0.2, 0.2). It matches default GL_LIGHT_MODEL_AMBIENT in fixed-function OpenGL. It also matches the required value of VRML 1.0 specification. For VRML 2.0 / X3D, lighting equations suggest that it should be zero.

Public property ProjectionMatrix: TMatrix4 read FProjectionMatrix write SetProjectionMatrix;

Current projection matrix.

When GLFeatures.EnableFixedFunction = true, setting this also sets fixed-function projection matrix.

Public property DepthRange: TDepthRange read FDepthRange write SetDepthRange;

Use this to operate on OpenGL glDepthRange. For now, our engine has very simple use for this, for TPlayer.RenderOnTop.

Public property CullFace: boolean read FCullFace write SetCullFace default false;

Should we use backface-culling (ignore some faces during rendering). This controls whether OpenGL GL_CULL_FACE flag is enabled or not.

Public property FrontFaceCcw: boolean read FFrontFaceCcw write SetFrontFaceCcw default true;

Is the front face ordered counter-clockwise. The "front face" is important to interpreting the CullFace and to interpret the normal vectors (they point outward from front face).

Public property ColorMask: boolean read GetColorMask write SetColorMask default true; deprecated 'use ColorChannels';

Warning: this symbol is deprecated: use ColorChannels

Are color buffer channels changed by rendering.

Public property ColorChannels: TColorChannels read FColorChannels write SetColorChannels default [0..3];

Which color buffer channels are written by rendering. This affects all rendering, including TDrawableImage.Draw.

Note that this state may be internally modified by various engine rendering functions too, e.g. by TCastleScene.LocalRender, depending on rendering attributes. So it is only reliable for you to modify this temporarily, and during your own rendering. E.g. change ColorChannels right before and right after calling a couple of TDrawableImage.Draw. Always restore it afterwards to default [0..3].

Example uses:

  • Set this to ccNone to temporarily turn off writing to the color buffer. This is useful e.g. if you only want to write to the delph and stencil buffer.

  • Set this to [0..2] to temporarily turn off writing to the alpha channel, or to [3] to temporarily turn off writing to the RGB channels.

  • Set this [0..3] to go back to default (write all channels).

Public property DepthBufferUpdate: Boolean read FDepthBufferUpdate write SetDepthBufferUpdate default true;

Is depth buffer updated by rendering. This affects all rendering that enables depth testing (which in practice means only TCastleScene in CGE).

Public property Viewport: TRectangle read FViewport write SetViewport;

Controls OpenGL viewport. This is always shifted by ViewportDelta.

Public property ViewportDelta: TVector2Integer read FViewportDelta write SetViewportDelta;

Shifts the rectangle passed to Viewport. Only the TCastleScreenEffects should control this.

Public property CurrentProgram: TGLSLProgram read FCurrentProgram write SetCurrentProgram;

Currently enabled GLSL program. Nil if fixed-function pipeline should be used. Setting this property encapsulates the OpenGL glUseProgram (or equivalent ARB extension), additionally preventing redundant glUseProgram calls.

Generated by PasDoc 0.16.0.