Unit CastleGLUtils

Description

Uses

Classes, Interfaces, Objects and Records

Functions and Procedures

Types

Constants

Variables

Description

Various utilities for OpenGL(ES) rendering.

Uses

Overview

Classes, Interfaces, Objects and Records

Name	Description
Class `TGLMemoryInfo`	OpenGL memory information.
Class `TGLFeatures`	OpenGL(ES) features, analyzed based on extensions and version.
Record `TLineStipple`
Class `TVertexArrayObject`	Vertex array object.

Functions and Procedures

procedure GLInformationInitialize;

function StrToCapabilities(const S: String): TGLRequestCapabilities;

procedure DrawRectangle(const R: TRectangle; const Color: TCastleColor; const BlendingSourceFactor: TBlendingSourceFactor = bsSrcAlpha; const BlendingDestinationFactor: TBlendingDestinationFactor = bdOneMinusSrcAlpha; const ForceBlending: boolean = false); overload;

procedure DrawRectangle(const R: TFloatRectangle; const Color: TCastleColor; const BlendingSourceFactor: TBlendingSourceFactor = bsSrcAlpha; const BlendingDestinationFactor: TBlendingDestinationFactor = bdOneMinusSrcAlpha; const ForceBlending: boolean = false); overload;

procedure DrawRectangleOutline(const R: TRectangle; const Color: TCastleColor; const LineWidth: Single = 1; const BlendingSourceFactor: TBlendingSourceFactor = bsSrcAlpha; const BlendingDestinationFactor: TBlendingDestinationFactor = bdOneMinusSrcAlpha; const ForceBlending: boolean = false); overload;

procedure DrawRectangleOutline(const R: TFloatRectangle; const Color: TCastleColor; const LineWidth: Single = 1; const BlendingSourceFactor: TBlendingSourceFactor = bsSrcAlpha; const BlendingDestinationFactor: TBlendingDestinationFactor = bdOneMinusSrcAlpha; const ForceBlending: boolean = false); overload;

procedure DrawCircle(const Middle: TVector2Integer; const HorizontalRadius, VerticalRadius: Integer; const Color: TCastleColor; const CircleSlices: Cardinal = DefaultCircleSlices; const BlendingSourceFactor: TBlendingSourceFactor = bsSrcAlpha; const BlendingDestinationFactor: TBlendingDestinationFactor = bdOneMinusSrcAlpha; const ForceBlending: boolean = false); overload;

procedure DrawCircle(const Middle: TVector2; const HorizontalRadius, VerticalRadius: Single; const Color: TCastleColor; const CircleSlices: Cardinal = DefaultCircleSlices; const BlendingSourceFactor: TBlendingSourceFactor = bsSrcAlpha; const BlendingDestinationFactor: TBlendingDestinationFactor = bdOneMinusSrcAlpha; const ForceBlending: boolean = false); overload;

procedure DrawCircleOutline(const Middle: TVector2Integer; const HorizontalRadius, VerticalRadius: Integer; const Color: TCastleColor; const LineWidth: Single = 1; const CircleSlices: Cardinal = DefaultCircleSlices; const BlendingSourceFactor: TBlendingSourceFactor = bsSrcAlpha; const BlendingDestinationFactor: TBlendingDestinationFactor = bdOneMinusSrcAlpha; const ForceBlending: boolean = false); overload;

procedure DrawCircleOutline(const Middle: TVector2; const HorizontalRadius, VerticalRadius: Single; const Color: TCastleColor; const LineWidth: Single = 1; const CircleSlices: Cardinal = DefaultCircleSlices; const BlendingSourceFactor: TBlendingSourceFactor = bsSrcAlpha; const BlendingDestinationFactor: TBlendingDestinationFactor = bdOneMinusSrcAlpha; const ForceBlending: boolean = false); overload;

procedure DrawPrimitive2D(const Mode: TPrimitiveMode; const Points: array of TVector2SmallInt; const Color: TCastleColor; const BlendingSourceFactor: TBlendingSourceFactor = bsSrcAlpha; const BlendingDestinationFactor: TBlendingDestinationFactor = bdOneMinusSrcAlpha; const ForceBlending: boolean = false; const LineWidth: Single = 1; const PointSize: Cardinal = 1); overload;

procedure DrawPrimitive2D(const Mode: TPrimitiveMode; const Points: array of TVector2; const Color: TCastleColor; const BlendingSourceFactor: TBlendingSourceFactor = bsSrcAlpha; const BlendingDestinationFactor: TBlendingDestinationFactor = bdOneMinusSrcAlpha; const ForceBlending: boolean = false; const LineWidth: Single = 1; const PointSize: Cardinal = 1); overload;

procedure DrawPrimitive2D(const Mode: TPrimitiveMode; const LineStipple: TLineStipple; const Points: array of TVector2; const Color: TCastleColor; const BlendingSourceFactor: TBlendingSourceFactor = bsSrcAlpha; const BlendingDestinationFactor: TBlendingDestinationFactor = bdOneMinusSrcAlpha; const ForceBlending: boolean = false; const LineWidth: Single = 1; const PointSize: Cardinal = 1); overload;

procedure GLFadeRectangleDark(const X1, Y1, X2, Y2: Integer; const AFadeColor: TVector3; const FadeIntensity: Single); overload;

procedure GLFadeRectangleDark(const Rect: TRectangle; const AFadeColor: TCastleColor; const FadeIntensity: Single); overload;

procedure GLFadeRectangleDark(const Rect: TFloatRectangle; const AFadeColor: TCastleColor; const FadeIntensity: Single); overload;

procedure GLFadeRectangleLight(const Rect: TRectangle; const AFadeColor: TCastleColor; const FadeIntensity: Single); overload;

procedure GLFadeRectangleLight(const Rect: TFloatRectangle; const AFadeColor: TCastleColor; const FadeIntensity: Single); overload;

procedure GLFadeRectangle(const X1, Y1, X2, Y2: Integer; const AFadeColor: TVector3; const FadeIntensity: Single); overload; deprecated 'use GLFadeRectangleDark, or TCastleFlashEffect with Dark = true';

procedure GLFadeRectangle(const Rect: TRectangle; const AFadeColor: TCastleColor; const FadeIntensity: Single); overload; deprecated 'use GLFadeRectangleDark, or TCastleFlashEffect with Dark = true';

procedure GLBlendRectangle(const X1, Y1, X2, Y2: Integer; const SourceFactor: TBlendingSourceFactor; const DestinationFactor: TBlendingDestinationFactor; const Color: TVector4); overload; deprecated 'use DrawRectangle';

procedure GLBlendRectangle(const Rect: TRectangle; const Color: TVector4); overload; deprecated 'use DrawRectangle';

procedure GLBlendFunction( SourceFactor: TBlendingSourceFactor; DestinationFactor: TBlendingDestinationFactor); deprecated 'use RenderContext.BlendingEnable';

function GLInformationString: String;

function GLInformationStringSummary: String;

Types

TGLenum = GLenum;

TGLboolean = GLboolean;

TGLbitfield = GLbitfield;

TGLbyte = GLbyte;

TGLshort = GLshort;

TGLint = GLint;

TGLsizei = GLsizei;

TGLubyte = GLubyte;

TGLushort = GLushort;

TGLuint = GLuint;

TGLfloat = GLfloat;

TGLclampf = GLclampf;

TGLdouble = GLdouble;

TGLclampd = GLclampd;

TGLRequestCapabilities = (...);

TPrimitiveMode = (...);

Constants

CapabilitiesStr: array [TGLRequestCapabilities] of String = (
    'automatic',
    'force-fixed-function',
    'force-modern'
  );

DefaultCircleSlices = 32;

Variables

GLFeatures: TGLFeatures;

LogGLInformationVerbose: Boolean = false;

Description

Functions and Procedures

procedure GLInformationInitialize;

Initialize GLVersion and GLFeatures.

function StrToCapabilities(const S: String): TGLRequestCapabilities;

Convert a string (like command-line argument) to TGLRequestCapabilities.

procedure DrawRectangle(const R: TRectangle; const Color: TCastleColor; const BlendingSourceFactor: TBlendingSourceFactor = bsSrcAlpha; const BlendingDestinationFactor: TBlendingDestinationFactor = bdOneMinusSrcAlpha; const ForceBlending: boolean = false); overload;

Draw a rectangle filled with a color.

Like with DrawPrimitive2D: Blending is automatically used if Color alpha < 1. ForceBlending forces the usage of blending. When it is False, we use blending only if Color[3] (alpha) < 1.

procedure DrawRectangle(const R: TFloatRectangle; const Color: TCastleColor; const BlendingSourceFactor: TBlendingSourceFactor = bsSrcAlpha; const BlendingDestinationFactor: TBlendingDestinationFactor = bdOneMinusSrcAlpha; const ForceBlending: boolean = false); overload;

This item has no description.

procedure DrawRectangleOutline(const R: TRectangle; const Color: TCastleColor; const LineWidth: Single = 1; const BlendingSourceFactor: TBlendingSourceFactor = bsSrcAlpha; const BlendingDestinationFactor: TBlendingDestinationFactor = bdOneMinusSrcAlpha; const ForceBlending: boolean = false); overload;

Draw a rectangle frame.

Like with DrawPrimitive2D: Blending is automatically used if Color alpha < 1. ForceBlending forces the usage of blending. When it is False, we use blending only if Color[3] (alpha) < 1.

procedure DrawRectangleOutline(const R: TFloatRectangle; const Color: TCastleColor; const LineWidth: Single = 1; const BlendingSourceFactor: TBlendingSourceFactor = bsSrcAlpha; const BlendingDestinationFactor: TBlendingDestinationFactor = bdOneMinusSrcAlpha; const ForceBlending: boolean = false); overload;

This item has no description.

procedure DrawCircle(const Middle: TVector2Integer; const HorizontalRadius, VerticalRadius: Integer; const Color: TCastleColor; const CircleSlices: Cardinal = DefaultCircleSlices; const BlendingSourceFactor: TBlendingSourceFactor = bsSrcAlpha; const BlendingDestinationFactor: TBlendingDestinationFactor = bdOneMinusSrcAlpha; const ForceBlending: boolean = false); overload;

Draw a circle. It may be scaled differently in X than Y, thus resembling an ellipse.

Like with DrawPrimitive2D: Blending is automatically used if Color alpha < 1. ForceBlending forces the usage of blending. When it is False, we use blending only if Color[3] (alpha) < 1.

procedure DrawCircle(const Middle: TVector2; const HorizontalRadius, VerticalRadius: Single; const Color: TCastleColor; const CircleSlices: Cardinal = DefaultCircleSlices; const BlendingSourceFactor: TBlendingSourceFactor = bsSrcAlpha; const BlendingDestinationFactor: TBlendingDestinationFactor = bdOneMinusSrcAlpha; const ForceBlending: boolean = false); overload;

This item has no description.

procedure DrawCircleOutline(const Middle: TVector2Integer; const HorizontalRadius, VerticalRadius: Integer; const Color: TCastleColor; const LineWidth: Single = 1; const CircleSlices: Cardinal = DefaultCircleSlices; const BlendingSourceFactor: TBlendingSourceFactor = bsSrcAlpha; const BlendingDestinationFactor: TBlendingDestinationFactor = bdOneMinusSrcAlpha; const ForceBlending: boolean = false); overload;

Draw a circle outline. It may be scaled differently in X than Y, thus resembling an ellipse.

Like with DrawPrimitive2D: Blending is automatically used if Color alpha < 1. ForceBlending forces the usage of blending. When it is False, we use blending only if Color[3] (alpha) < 1.

procedure DrawCircleOutline(const Middle: TVector2; const HorizontalRadius, VerticalRadius: Single; const Color: TCastleColor; const LineWidth: Single = 1; const CircleSlices: Cardinal = DefaultCircleSlices; const BlendingSourceFactor: TBlendingSourceFactor = bsSrcAlpha; const BlendingDestinationFactor: TBlendingDestinationFactor = bdOneMinusSrcAlpha; const ForceBlending: boolean = false); overload;

This item has no description.

procedure DrawPrimitive2D(const Mode: TPrimitiveMode; const Points: array of TVector2SmallInt; const Color: TCastleColor; const BlendingSourceFactor: TBlendingSourceFactor = bsSrcAlpha; const BlendingDestinationFactor: TBlendingDestinationFactor = bdOneMinusSrcAlpha; const ForceBlending: boolean = false; const LineWidth: Single = 1; const PointSize: Cardinal = 1); overload;

Draw a simple 2D primitive with a given color. This can be used to draw a series of points, lines or triangles, depending on the Mode parameter.

Blending is automatically used if Color alpha < 1. ForceBlending forces the usage of blending. When it is False, we use blending only if Color[3] (alpha) < 1.

Parameters

LineWidth

Line width, only used when Mode indicates lines.

Note that values other than 1 are not guaranteed to be supported. While it's a fast method to have thick lines, it is implementation-limited in case of

desktop OpenGL with anti-aliasing, see https://www.opengl.org/sdk/docs/man/html/glLineWidth.xhtml
mobile OpenGLES, with or without anti-aliasing, see https://www.khronos.org/opengles/sdk/docs/man/xhtml/glLineWidth.xml

PointSize

Point size, only used when Mode indicates points.

Note that values other than 1 are not guaranteed to be supported. Mobile OpenGLES does not support setting point size like this. And desktop OpenGL limits point size in case anti-aliasing is used, see https://www.opengl.org/sdk/docs/man2/xhtml/glPointSize.xml .

procedure DrawPrimitive2D(const Mode: TPrimitiveMode; const Points: array of TVector2; const Color: TCastleColor; const BlendingSourceFactor: TBlendingSourceFactor = bsSrcAlpha; const BlendingDestinationFactor: TBlendingDestinationFactor = bdOneMinusSrcAlpha; const ForceBlending: boolean = false; const LineWidth: Single = 1; const PointSize: Cardinal = 1); overload;

This item has no description.

procedure DrawPrimitive2D(const Mode: TPrimitiveMode; const LineStipple: TLineStipple; const Points: array of TVector2; const Color: TCastleColor; const BlendingSourceFactor: TBlendingSourceFactor = bsSrcAlpha; const BlendingDestinationFactor: TBlendingDestinationFactor = bdOneMinusSrcAlpha; const ForceBlending: boolean = false; const LineWidth: Single = 1; const PointSize: Cardinal = 1); overload;

Draw primitive, using a stipple (pattern) for line rendering. Note that the stipple is ignored on mobile (OpenGLES).

procedure GLFadeRectangleDark(const X1, Y1, X2, Y2: Integer; const AFadeColor: TVector3; const FadeIntensity: Single); overload;

Draw a rectangle that modulates colors underneath, making nice animation to AFadeColor while FadeIntensity changes from 1.0 down to 0.0.

The GLFadeRectangleLight version makes a flash to AFadeColor, then goes back to normal. It works reasonably with any color (light or dark).

The GLFadeRectangleDark version makes additional flash to blackness in the middle (so it goes from no modulation, to AFadeColor, to pure black, and then back to normal). So the "Dark" version is a little more impressive when you're flashing with a dark color.

These are nice as a screen effect, to flash some color (e.g. flash red color when the player is hurt).

Only RGB portion of AFadeColor is used.

procedure GLFadeRectangleDark(const Rect: TRectangle; const AFadeColor: TCastleColor; const FadeIntensity: Single); overload;

This item has no description.

procedure GLFadeRectangleDark(const Rect: TFloatRectangle; const AFadeColor: TCastleColor; const FadeIntensity: Single); overload;

This item has no description.

procedure GLFadeRectangleLight(const Rect: TRectangle; const AFadeColor: TCastleColor; const FadeIntensity: Single); overload;

This item has no description.

procedure GLFadeRectangleLight(const Rect: TFloatRectangle; const AFadeColor: TCastleColor; const FadeIntensity: Single); overload;

This item has no description.

procedure GLFadeRectangle(const X1, Y1, X2, Y2: Integer; const AFadeColor: TVector3; const FadeIntensity: Single); overload; deprecated 'use GLFadeRectangleDark, or TCastleFlashEffect with Dark = true';

Warning: this symbol is deprecated: use GLFadeRectangleDark, or TCastleFlashEffect with Dark = true

This item has no description.

procedure GLFadeRectangle(const Rect: TRectangle; const AFadeColor: TCastleColor; const FadeIntensity: Single); overload; deprecated 'use GLFadeRectangleDark, or TCastleFlashEffect with Dark = true';

Warning: this symbol is deprecated: use GLFadeRectangleDark, or TCastleFlashEffect with Dark = true

This item has no description.

procedure GLBlendRectangle(const X1, Y1, X2, Y2: Integer; const SourceFactor: TBlendingSourceFactor; const DestinationFactor: TBlendingDestinationFactor; const Color: TVector4); overload; deprecated 'use DrawRectangle';

Warning: this symbol is deprecated: use DrawRectangle

Draw a rectangle with blending. Deprecated, use DrawRectangle instead.

procedure GLBlendRectangle(const Rect: TRectangle; const Color: TVector4); overload; deprecated 'use DrawRectangle';

Warning: this symbol is deprecated: use DrawRectangle

This item has no description.

procedure GLBlendFunction( SourceFactor: TBlendingSourceFactor; DestinationFactor: TBlendingDestinationFactor); deprecated 'use RenderContext.BlendingEnable';

Warning: this symbol is deprecated: use RenderContext.BlendingEnable

Call OpenGL glBlendFunc. Accepts parameters as enumerated types TBlendingSourceFactor, TBlendingDestinationFactor. Secures from using source or destination factor unsupported on current OpenGL version: makes a warnings and falls back on a sensible default (so it will always call glBlendFunc anyway).

function GLInformationString: String;

Multiline string describing attributes of current OpenGL(ES) library. This simply queries OpenGL(ES) using glGet* functions about many things. Does not change OpenGL(ES) state in any way.

Note that the last line of returned string does not terminate with a newline character (so e.g. you may want to do Writeln(GLInformationString) instead of just Write(GLInformationString)).

function GLInformationStringSummary: String;

One-line string summarizing current OpenGL(ES).

Types

TGLenum = GLenum;

This item has no description.

TGLboolean = GLboolean;

This item has no description.

TGLbitfield = GLbitfield;

This item has no description.

TGLbyte = GLbyte;

This item has no description.

TGLshort = GLshort;

This item has no description.

TGLint = GLint;

This item has no description.

TGLsizei = GLsizei;

This item has no description.

TGLubyte = GLubyte;

This item has no description.

TGLushort = GLushort;

This item has no description.

TGLuint = GLuint;

This item has no description.

TGLfloat = GLfloat;

This item has no description.

TGLclampf = GLclampf;

This item has no description.

TGLdouble = GLdouble;

This item has no description.

TGLclampd = GLclampd;

This item has no description.

TGLRequestCapabilities = (...);

OpenGL(ES) capabilities to request at context creation. Use with TGLFeatures.RequestCapabilities.

Values

rcAutomatic: Use modern GPU code (shaders, VBO etc.) unless it is not possible (not supported by GPU). This is the default mode.
GLFeatures.EnableFixedFunction may be False (preferred) or True (fallback).
TODO: At some point, rcAutomatic will automatically require modern context with deprecated functionality removed (just like rcForceModern) and only fallback on non-modern context if that is not possible. For now, rcAutomatic still initializes context with compatibility entry points too, although it will not use them if the resulting context is modern. We use flag rcForceModern to test whether the "modern (core) context with deprecated stuff removed" is worth the hassle, i.e. is there a practical benefit (measurable speedup / functionality boost) of not having compatibility entry points.
rcForceFixedFunction: Force using deprecated fixed-function even on modern GPUs. Should only be used to test our fixed-function code, never use this in production code – you should always strive to use modern GPU code.
GLFeatures.EnableFixedFunction will be always True.
We will keep OpenGL API usage at 1.x, for large things (no shaders, no VBO) and small things (like querying OpenGL extensions). The goal is to really simulate ancient GPU, before shaders were part of the OpenGL standard.
Not possible on OpenGLES, where CGE always uses modern shader pipeline.
rcForceModern: Force initializing modern OpenGL context, with deprecated functionality not available.
Modern context requires support for modern functionality (like shaders) and may actually remove support for deprecated functionality (like fixed-function). This may provide some additional speedup / functionality at some point (but nothing you can really observe in practice, for now, in my experience).
Using this guarantees you always have GLFeatures.EnableFixedFunction = False.
On platforms where we honor this flag at context creation (using glX etc.): This even guarantees more: that at least OpenGL version 3.3 (TGLFeatures.ModernVersionMajor, TGLFeatures.ModernVersionMinor) is available. In exchange, it really prohibits using any older deprecated OpenGL API. So the code must, when Version_3_3 (or maybe from earlier versions for each functionality), use new OpenGL API (and not any deprecated API).
The specifics what it does: We try to initialize "core" profile of OpenGL version 3.3 (TGLFeatures.ModernVersionMajor, TGLFeatures.ModernVersionMinor).

TPrimitiveMode = (...);

Primitive to draw using DrawPrimitive2D. The modes correspond to OpenGL drawing modes, see https://www.opengl.org/wiki/Primitive https://www.opengl.org/sdk/docs/man2/xhtml/glBegin.xml

Values

pmPoints
pmLineStrip
pmLineLoop
pmLines
pmTriangleStrip
pmTriangleFan
pmTriangles

Constants

CapabilitiesStr: array [TGLRequestCapabilities] of String = (
    'automatic',
    'force-fixed-function',
    'force-modern'
  );

This item has no description.

DefaultCircleSlices = 32;

This item has no description.

Variables

GLFeatures: TGLFeatures;

This item has no description.

LogGLInformationVerbose: Boolean = false;

Much more verbose logging of current context capabilities in GLInformationInitialize.

Generated by PasDoc 0.16.0-snapshot.

API Reference

Unit CastleGLUtils

Description

Uses

Overview

Classes, Interfaces, Objects and Records

Functions and Procedures

Types

Constants

Variables

Description

Functions and Procedures

Parameters

Types

Values

Values

Constants

Variables