Castle Game EngineIntroduction Units Class Hierarchy Classes, Interfaces, Objects and Records Types Variables Constants Functions and Procedures Identifiers |
Unit CastleGLUtils
Description
Various low-level utilities for working with OpenGL.
Uses
Overview
Classes, Interfaces, Objects and Records
Functions and Procedures
procedure GLInformationInitialize; |
procedure GLOutOfMemory(const AdditionalComment: string = ''); |
function GLErrorString(const ErrorCode: TGLenum; const AdditionalComment: string = ''): string; |
procedure CheckGLErrors(const AdditionalComment: string = ''); |
procedure GLErrorRaise(ErrorCode: TGLenum); cdecl; |
function glGetFloat(pname: TGLEnum): TGLfloat; |
function glGetInteger(pname: TGLEnum): TGLint; |
function glGetBoolean(pname: TGLEnum): TGLboolean; |
procedure glColorv(const v: TVector3ub); overload; |
procedure glColorv(const v: TVector4ub); overload; |
procedure glColorv(const v: TVector3f); overload; |
procedure glColorv(const v: TVector4f); overload; |
procedure glTranslatev(const V: TVector3f); overload; |
procedure glTranslatev(const V: TVector3_Single); overload; |
procedure glScalev(const V: Single); overload; |
procedure glScalev(const V: TVector3f); overload; |
procedure glScalev(const V: TVector3_Single); overload; |
procedure glRotatev(const Angle: TGLfloat; const V: TVector3f); overload; |
procedure glClipPlane(plane: GLenum; const V: TVector4d); overload; |
procedure glNormalv(const v: TVector3f); overload; |
procedure glMaterialv(face, pname: TGLEnum; const params: TVector4f); overload; |
procedure glVertexv(const v: TVector2f); overload; |
procedure glVertexv(const v: TVector2i); overload; |
procedure glVertexv(const v: TVector3f); overload; |
procedure glVertexv(const v: TVector3i); overload; |
procedure glVertexv(const v: TVector4f); overload; |
procedure glVertexv(const v: TVector4i); overload; |
procedure glVertexv(const v: TVector2_Single); overload; |
procedure glVertexv(const v: TVector3_Single); overload; |
procedure glVertexv(const v: TVector4_Single); overload; |
procedure glTexCoordv(const v: TVector2f); overload; |
procedure glTexCoordv(const v: TVector3f); overload; |
procedure glTexCoordv(const v: TVector4f); overload; |
procedure glTexGenv(coord, pname: TGLenum; const params: TVector4f); overload; |
procedure glLightv(light, pname: TGLEnum; const params: TVector4f); overload; |
procedure glLightv(light, pname: TGLEnum; const params: TVector3f); overload; |
procedure glLightModelv(pname: TGLenum; const params: TVector4f); overload; |
procedure glFogv(pname: TGLEnum; const params: TVector4f); overload; |
procedure glMultMatrix(const m: TMatrix4f); overload; |
procedure glLoadMatrix(const m: TMatrix4f); overload; |
procedure glTexEnvv(target, pname: TGLEnum; const params: TVector4f); overload; |
procedure GLViewport(const Rect: TRectangle); |
function GetCurrentColor: TCastleColor; |
procedure SetCurrentColor(const Value: TCastleColor); |
procedure BeforeUnpackNotAlignedRGBImage(out unpackdata: TUnpackNotAlignedData; imageWidth: cardinal); |
procedure AfterUnpackNotAlignedRGBImage(const unpackData: TUnpackNotAlignedData; imageWidth: cardinal); |
procedure BeforeUnpackImage(out unpackdata: TUnpackNotAlignedData; image: TCastleImage); |
procedure AfterUnpackImage(const unpackData: TUnpackNotAlignedData; image: TCastleImage); |
procedure BeforePackImage(out packdata: TPackNotAlignedData; image: TCastleImage); |
procedure AfterPackImage(const packData: TPackNotAlignedData; image: TCastleImage); |
function GetProjectionMatrix: TMatrix4Single; |
procedure SetProjectionMatrix(const Value: TMatrix4Single); |
function PerspectiveProjection(const fovy, aspect, zNear, zFar: Single): TMatrix4Single; |
function OrthoProjection(const left, right, bottom, top: Single; const zNear: Single = -1; const zFar: Single = 1): TMatrix4Single; |
procedure GLSetEnabled(value: TGLenum; isEnabled: boolean); |
procedure GLVerticalLine(x, y1, y2: TGLfloat); deprecated; |
procedure GLHorizontalLine(x1, x2, y: TGLfloat); deprecated; |
procedure GLDrawArrow(HeadThickness: TGLfloat = 0.4; HeadLength: TGLfloat = 0.5); |
function NewGLUQuadric( Texture: boolean = true; Normals: TGLenum = GLU_NONE; Orientation: TGLenum = GLU_OUTSIDE; DrawStyle: TGLenum = GLU_FILL): PGLUQuadric; overload; |
procedure CastleGluSphere( const Radius: TGLdouble; const Slices, Stacks: TGLint; Texture: boolean = true; Normals: TGLenum = GLU_NONE; Orientation: TGLenum = GLU_OUTSIDE; DrawStyle: TGLenum = GLU_FILL); |
procedure glDrawAxisWire(const Position: TVector3Single; Size: Single); |
procedure glDrawCornerMarkers(const Box: TBox3D; const Proportion: Single = 0.1); |
procedure glDrawBox3DWire(const Box: TBox3D); |
procedure glDrawBox3DSimple(const Box: TBox3D); |
procedure glColorOpacity(const Color: TVector3Single; const Opacity: Single); deprecated; |
procedure glColorOpacity(const Color: TVector3Byte; const Opacity: Single); deprecated; |
procedure GLFadeRectangle(const X1, Y1, X2, Y2: Integer; const FadeColor: TVector3Single; const FadeIntensity: Single); deprecated; |
procedure GLFadeRectangle(const Rect: TRectangle; const FadeColor: TCastleColor; const FadeIntensity: Single); |
procedure GLBlendRectangle(const X1, Y1, X2, Y2: Integer; const SourceFactor, DestinationFactor: TGLenum; const Color: TVector4Single); deprecated; |
procedure GLBlendRectangle(const Rect: TRectangle; const Color: TVector4Single); deprecated; |
procedure DrawRectangle(const R: TRectangle; const Color: TCastleColor; const BlendingSourceFactor: TGLEnum = GL_SRC_ALPHA; const BlendingDestinationFactor: TGLEnum = GL_ONE_MINUS_SRC_ALPHA; const ForceBlending: boolean = false); |
function GLInformationString: string; |
function glGenListsCheck(range: TGLsizei; const Place: string): TGLuint; |
procedure glFreeDisplayList(var list: TGLuint); |
procedure glFreeTexture(var Tex: TGLuint); |
procedure glFreeBuffer(var Buffer: TGLuint); |
procedure glSetDepthAndColorWriteable(Writeable: TGLboolean); |
procedure SetWindowPos(const X, Y: TGLint); |
procedure SetWindowPos(const Value: TVector2i); |
procedure SetWindowPosF(const X, Y: TGLfloat); deprecated; |
procedure SetWindowPosZero; deprecated; |
function GetWindowPos: TVector2i; |
function GetDepthRange: TDepthRange; |
procedure SetDepthRange(const Value: TDepthRange); |
function GLEnableTexture(const Target: TEnableTextureTarget): boolean; |
procedure GLClear(const Buffers: TClearBuffers; const ClearColor: TCastleColor); |
procedure ScissorEnable(const Rect: TRectangle); |
procedure ScissorDisable; |
function GetGlobalAmbient: TVector3Single; |
procedure SetGlobalAmbient(const Value: TVector3Single); |
Types
Constants
Variables
Description
Functions and Procedures
procedure GLOutOfMemory(const AdditionalComment: string = ''); |
|
function GLErrorString(const ErrorCode: TGLenum; const AdditionalComment: string = ''): string; |
|
procedure CheckGLErrors(const AdditionalComment: string = ''); |
Check are any OpenGL errors recorded (in glGetError). If there are errors, our behavior depends on whether we were compiled with -dRELEASE. With -dRELEASE, we make OnWarning. This way eventual errors in release builds don't completely abort your program.
Note that the behavior on GL_OUT_OF_MEMORY is different. -dRELEASE does not matter here. Only GLOutOfMemoryError boolean dictates if we should raise an exception or merely make warning, regardless of -dRELEASE state.
Without -dRELEASE, we raise EOpenGLError. So a developer is strongly suggested to fix the code to not produce OpenGL errors, never ever.
Exceptions raised
- EOpenGLError
|
procedure GLErrorRaise(ErrorCode: TGLenum); cdecl; |
Raise EOpenGLError for given OpenGL error code. This has calling convention suitable for registering this procedure as GLU_TESS_ERROR for gluTessCallback, or GLU_ERROR for gluQuadricCallback.
|
function glGetFloat(pname: TGLEnum): TGLfloat; |
Comfortable wrappers for OpenGL glGet* that return a single value.
Guarantee that result is zero in case of OpenGL error. (Otherwise, OpenGL could leave them undefined and only set glGetError.)
|
procedure glColorv(const v: TVector3ub); overload; |
|
procedure glColorv(const v: TVector4ub); overload; |
|
procedure glColorv(const v: TVector3f); overload; |
|
procedure glColorv(const v: TVector4f); overload; |
|
procedure glTranslatev(const V: TVector3f); overload; |
|
procedure glTranslatev(const V: TVector3_Single); overload; |
|
procedure glScalev(const V: Single); overload; |
|
procedure glScalev(const V: TVector3f); overload; |
|
procedure glScalev(const V: TVector3_Single); overload; |
|
procedure glClipPlane(plane: GLenum; const V: TVector4d); overload; |
|
procedure glNormalv(const v: TVector3f); overload; |
|
procedure glVertexv(const v: TVector2f); overload; |
|
procedure glVertexv(const v: TVector2i); overload; |
|
procedure glVertexv(const v: TVector3f); overload; |
|
procedure glVertexv(const v: TVector3i); overload; |
|
procedure glVertexv(const v: TVector4f); overload; |
|
procedure glVertexv(const v: TVector4i); overload; |
|
procedure glVertexv(const v: TVector2_Single); overload; |
|
procedure glVertexv(const v: TVector3_Single); overload; |
|
procedure glVertexv(const v: TVector4_Single); overload; |
|
procedure glTexCoordv(const v: TVector2f); overload; |
|
procedure glTexCoordv(const v: TVector3f); overload; |
|
procedure glTexCoordv(const v: TVector4f); overload; |
|
procedure glMultMatrix(const m: TMatrix4f); overload; |
|
procedure glLoadMatrix(const m: TMatrix4f); overload; |
|
procedure BeforeUnpackNotAlignedRGBImage(out unpackdata: TUnpackNotAlignedData; imageWidth: cardinal); |
Save/restore OpenGL pixel store for unpacking TRGBImage. Before you pass an TRGBImage to glDrawPixels, glTexImage1D, glTexImage2D, glBitmap, glPolygonStipple and such, call BeforeUnpackNotAlignedRGBImage , and later call AfterUnpackNotAlignedRGBImage to restore original state.
|
procedure BeforeUnpackImage(out unpackdata: TUnpackNotAlignedData; image: TCastleImage); |
Save/restore OpenGL pixel store for unpacking / packing given TCastleImage. Before you pass this image to some OpenGL procedures (like glDrawPixels for unpacking, glReadPixels for packing), call BeforeXxx, and later call AfterXxx to restore original state. These will take care of setting/restoring pixel alignment.
|
function GetProjectionMatrix: TMatrix4Single; |
Projection matrix ——————————————————–
|
function PerspectiveProjection(const fovy, aspect, zNear, zFar: Single): TMatrix4Single; |
Set ProjectionMatrix to perspective or orthogonal.
For PerspectiveProjection , ZFar may have special ZFarInfinity value to create a perspective projection with far plane set at infinity. Useful e.g. for z-fail shadow volumes.
|
function OrthoProjection(const left, right, bottom, top: Single; const zNear: Single = -1; const zFar: Single = 1): TMatrix4Single; |
|
procedure GLSetEnabled(value: TGLenum; isEnabled: boolean); |
|
procedure GLVerticalLine(x, y1, y2: TGLfloat); deprecated; |
Warning: this symbol is deprecated.
Draw vertical line using OpenGL. Uses current OpenGL color.
Deprecated, do not draw lines directly like this, instead use UI interface drawing like Theme.Draw and TGLImage.Draw.
|
procedure GLHorizontalLine(x1, x2, y: TGLfloat); deprecated; |
Warning: this symbol is deprecated.
Draw horizontal line using OpenGL. Uses current OpenGL color.
Deprecated, do not draw lines directly like this, instead use UI interface drawing like Theme.Draw and TGLImage.Draw.
|
procedure GLDrawArrow(HeadThickness: TGLfloat = 0.4; HeadLength: TGLfloat = 0.5); |
Draw arrow shape. Arrow is placed on Z = 0 plane, points to the up, has height = 2 (from y = 0 to y = 2) and width 1 (from x = -0.5 to 0.5).
Everything is drawn CCW when seen from standard view (x grows right, y up). Uses current OpenGL color.
|
function NewGLUQuadric( Texture: boolean = true; Normals: TGLenum = GLU_NONE; Orientation: TGLenum = GLU_OUTSIDE; DrawStyle: TGLenum = GLU_FILL): PGLUQuadric; overload; |
Comfortable wrapper for gluNewQuadric. Sets all quadric parameters. Sets also the GLU_ERROR callback to ReportGLerror.
Exceptions raised
Exception
- If gluNewQuadric fails (returns nil).
|
procedure CastleGluSphere( const Radius: TGLdouble; const Slices, Stacks: TGLint; Texture: boolean = true; Normals: TGLenum = GLU_NONE; Orientation: TGLenum = GLU_OUTSIDE; DrawStyle: TGLenum = GLU_FILL); |
Render sphere in OpenGL. Radius, Slices, Stacks have the same meaning as for gluSphere (in case they are not self-explanatory...). Other parameters set glu quadric parameters, see glu quadric documentation.
|
procedure glDrawAxisWire(const Position: TVector3Single; Size: Single); |
Draw axis (3 lines) around given position. Nothing is generated besides vertex positions — no normal vectors, no texture coords, nothing.
|
procedure glDrawCornerMarkers(const Box: TBox3D; const Proportion: Single = 0.1); |
Draw corner markers (3 lines) at the 8 corners of the box. Proportion is the fraction of the box length, the marker extends too.
|
procedure glDrawBox3DWire(const Box: TBox3D); |
Draw the wireframe box. Nothing is generated besides vertex positions — no normal vectors, no texture coords, nothing.
|
procedure glDrawBox3DSimple(const Box: TBox3D); |
Draw simple box. Nothing is generated besides vertex positions — no normal vectors, no texture coords, nothing. Order is CCW outside (so if you want, you can turn on backface culling yourself).
You must enable GL_VERTEX_ARRAY before using this. (It's not done automatically, as it's much faster to do it once for many glDrawBox3DSimple calls. Example — bzwgen city view behind building 1, with occlusion query used: FPC 150 vs 110 when GL_VERTEX_ARRAY is activated once in OcclusionBoxStateBegin, not here. Tested on fglrx on Radeon X1600 (chantal).)
It can be safely placed in a display list.
|
procedure glColorOpacity(const Color: TVector3Single; const Opacity: Single); deprecated; |
Warning: this symbol is deprecated.
Call glColor, taking Opacity as separate Single argument. Deprecated, do not use colors like that, instead pass TCastleColor to appropriate routines like TCastleFont.Print.
|
procedure glColorOpacity(const Color: TVector3Byte; const Opacity: Single); deprecated; |
Warning: this symbol is deprecated. |
procedure GLFadeRectangle(const X1, Y1, X2, Y2: Integer; const FadeColor: TVector3Single; const FadeIntensity: Single); deprecated; |
Warning: this symbol is deprecated.
Draw a rectangle that modulates colors underneath, suddenly changing it to FadeColor and then fading to blackness and then fading back to normal, as FadeIntensity goes down from 1.0 to 0.0. This is nice to use for a screen effect when player is hurt.
Only RGB portion of FadeColor is used.
|
procedure GLFadeRectangle(const Rect: TRectangle; const FadeColor: TCastleColor; const FadeIntensity: Single); |
|
procedure GLBlendRectangle(const X1, Y1, X2, Y2: Integer; const SourceFactor, DestinationFactor: TGLenum; const Color: TVector4Single); deprecated; |
Warning: this symbol is deprecated.
Draw a rectangle with blending. Deprecated, use DrawRectangle instead.
|
procedure GLBlendRectangle(const Rect: TRectangle; const Color: TVector4Single); deprecated; |
Warning: this symbol is deprecated. |
procedure DrawRectangle(const R: TRectangle; const Color: TCastleColor; const BlendingSourceFactor: TGLEnum = GL_SRC_ALPHA; const BlendingDestinationFactor: TGLEnum = GL_ONE_MINUS_SRC_ALPHA; const ForceBlending: boolean = false); |
Draw a simple rectangle filled with a color. 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.
|
function GLInformationString: string; |
Multiline string describing attributes of current OpenGL library. This simply queries OpenGL using glGet* functions about many things. Does not change OpenGL 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 glGenListsCheck(range: TGLsizei; const Place: string): TGLuint; |
Call glGenLists(range) and checks the result.
Exceptions raised
- EOpenGLNoMoreDisplayLists
- When glGenLists(Range) returned zero for non-zero Range. The exception's Message shows Place, which may describe where this is called — makes it easier to debug.
|
procedure glFreeDisplayList(var list: TGLuint); |
If List <> 0 then it does glDeleteList on List and sets List to 0. In other words this is simply glDeleteList but
only if List really should be deleted
sets List to 0 after deletion
|
procedure glFreeTexture(var Tex: TGLuint); |
If Tex <> 0 then it does glDeleteTextures on Tex and sets Tex to 0. In other words, this is a simple wrapper over glDeleteTextures that
checks if Tex really should be deleted
sets Tex to 0 to not free it once again
|
procedure glFreeBuffer(var Buffer: TGLuint); |
If Buffer <> 0 then it does glDeleteBuffers and sets Buffer to 0.
|
procedure glSetDepthAndColorWriteable(Writeable: TGLboolean); |
Set color and depth buffers writeable or not. This is just a shortcut for
glDepthMask(Writeable);
glColorMask(Writeable, Writeable, Writeable, Writeable);
|
procedure SetWindowPos(const X, Y: TGLint); |
Draw the 2D GUI stuff (like following GUI images and TCastleFont) with lower-left corner in the X,Y pixel. It's not adviced to use this, better use TGLImage.Draw(X,Y) or TCastleFont.Print(X,Y,string) methods.
|
procedure SetWindowPos(const Value: TVector2i); |
|
procedure SetWindowPosF(const X, Y: TGLfloat); deprecated; |
Warning: this symbol is deprecated. |
procedure SetWindowPosZero; deprecated; |
Warning: this symbol is deprecated. |
function GLEnableTexture(const Target: TEnableTextureTarget): boolean; |
Enable exactly one (or none, for Target=etNone) OpenGL texture target. Always use this instead of manually calling glDisable(GL_TEXTURE_2D) , glEnable(GL_TEXTURE_2D) and such. This makes sure to have at most one texture target enabled, and disable others.
Remember that this state is different for every texture unit in OpenGL, in case you use multi-texturing.
Remember that not all texture targets are guaranteed to be supported by OpenGL. Target=etNone and Target=et2D are always supported. For the rest, check appropriate GLFeatures property (before even creating a texture with such type). If you pass an unsupported target type to this procedure, it will be ignored (all targets will be disabled, like for Target=etNone).
Note that this is only for fixed-function OpenGL pipeline. Shader pipeline completely ignores the enabled state of texture units.
|
procedure GLClear(const Buffers: TClearBuffers; const ClearColor: TCastleColor); |
Clear OpenGL buffer contents. Never call OpenGL glClear or glClearColor, always use this procedure.
|
procedure ScissorEnable(const Rect: TRectangle); |
Enable or disable scissor. Always do it using these procedures, do not call glScissor or glEnable(GL_SCISSOR_TEST) / glDisable(GL_SCISSOR_TEST) yourself, or push/pop attrib.
|
procedure ScissorDisable; |
|
Types
TGLSupport = (...); |
Values
-
gsNone:
-
gsExtension:
-
gsStandard:
|
TGLbitfield = GLbitfield; |
|
TDepthRange = (...); |
Values
|
TEnableTextureTarget = (...); |
Values
-
etNone:
-
et2D:
-
etCubeMap:
-
et3D:
|
TClearBuffer = (...); |
Values
-
cbColor:
-
cbDepth:
-
cbStencil:
|
Constants
GLSupportNames: array [TGLSupport] of string =
( 'None', 'Extension', 'Standard' ); |
|
Variables
GLOutOfMemoryError: boolean = false; |
When GPU runs out of memory, raise exception (EOpenGLOutOfMemoryError) or merely make a warning. Merely making a warning is very risky (you risk all kinds of rendering artifacts), but sometimes the rendering is actually smooth even though GPU complains.
|
property ProjectionMatrix: TMatrix4Single
read GetProjectionMatrix write SetProjectionMatrix; |
Current projection matrix.
For OpenGLES, this is merely a global ProjectionMatrix variable. It must be passed to various shaders to honour the projection.
For desktop OpenGL, setting this also sets fixed-function projection matrix. The OpenGL matrix mode is temporarily changed to GL_PROJECTION, then changed back to GL_MODELVIEW.
|
property GlobalAmbient: TVector3Single
read GetGlobalAmbient 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.
|
|