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.
This unit contains a mixture of useful utilities. Simple wrappers for OpenGL procedures (like glVertexv, that is overloaded for various vector types, and calls appropriate version like glVertex3fv based on parameter type). Also simple drawing routines for basic primitives (boxes etc.). This unit does not assume that you initialized OpenGL in any particular way (e.g. using CastleWindow, Glut, SDL, or whatever).
Uses
Overview
Classes, Interfaces, Objects and Records
Functions and Procedures
procedure LoadAllExtensions; |
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 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 glClearColorv(const v: TVector3f; alpha: Single); |
procedure glNormalv(const v: TVector3f); overload; |
procedure glColorv(const v: TVector3f); overload; |
procedure glColorv(const v: TVector4f); 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 BeforeUnpackNotAlignedRGBImage(out unpackdata: TUnpackNotAlignedData; imageWidth: cardinal); |
procedure AfterUnpackNotAlignedRGBImage(const unpackData: TUnpackNotAlignedData; imageWidth: cardinal); |
procedure BeforePackNotAlignedRGBImage(out packdata: TPackNotAlignedData; imageWidth: cardinal); |
procedure AfterPackNotAlignedRGBImage(const packData: TPackNotAlignedData; 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 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); |
procedure GLHorizontalLine(x1, x2, y: TGLfloat); |
procedure GLRectangleWithBorder(const x1, y1, x2, y2: TGLfloat; const InsideColor, BorderColor: TVector4f; const BorderWidth: Single = 1.0); |
procedure GLRectangleBorder(const x1, y1, x2, y2: TGLfloat; const Color: TVector4f; const BorderWidth: Single = 1.0); overload; |
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 glDrawBox3DWire(const Box: TBox3D); |
procedure glDrawBox3DSimple(const Box: TBox3D); |
procedure GLFadeRectangle(const X1, Y1, X2, Y2: Integer; const FadeColor: TVector3Single; const FadeIntensity: Single); |
procedure GLBlendRectangle(const X1, Y1, X2, Y2: Integer; const SourceFactor, DestinationFactor: TGLenum; const Color: TVector4Single); |
function GLInformationString: string; |
function glGenListsCheck(range: TGLsizei; const Place: string): TGLuint; |
procedure glFreeDisplayList(var list: TGLuint); |
procedure glFreeTexture(var Tex: 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; |
procedure glColorOpacity(const Color: TVector3Single; const Opacity: Single); |
procedure glColorOpacity(const Color: TVector3Byte; const Opacity: Single); |
function GetDepthRange: TDepthRange; |
procedure SetDepthRange(const Value: TDepthRange); |
function GLEnableTexture(const Target: TEnableTextureTarget): boolean; |
Types
Constants
Variables
Description
Functions and Procedures
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.
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 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 glClearColorv(const v: TVector3f; alpha: Single); |
|
procedure glNormalv(const v: TVector3f); overload; |
|
procedure glColorv(const v: TVector3f); overload; |
|
procedure glColorv(const v: 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 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 BeforePackNotAlignedRGBImage(out packdata: TPackNotAlignedData; imageWidth: cardinal); |
Save/restore OpenGL pixel store for packing TRGBImage. Use around glReadPixels and such with TRGBImage.
|
procedure AfterPackNotAlignedRGBImage(const packData: TPackNotAlignedData; imageWidth: cardinal); |
|
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 PerspectiveProjection(const fovy, aspect, zNear, zFar: Single): TMatrix4Single; |
Load projection matrix to OpenGL GL_PROJECTION matrix.
At the end, these unconditionally change matrix mode to GL_MODELVIEW.
ZFar is allowed to have special ZFarInfinity value for PerspectiveProjection . Then we set special perspective matrix, that has far plane set at infinity — useful 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); |
Draw vertical line using OpenGL. Uses current OpenGL color.
|
procedure GLHorizontalLine(x1, x2, y: TGLfloat); |
Draw horizontal line using OpenGL. Uses current OpenGL color.
|
procedure GLRectangleWithBorder(const x1, y1, x2, y2: TGLfloat; const InsideColor, BorderColor: TVector4f; const BorderWidth: Single = 1.0); |
Draw rectangle, filled with one color and framed with other color.
The vertex order is the same as for glRectf, so it's CCW from standard view. We assume that OpenGL polygon fill mode is "fill". Changes OpenGL current color and line width.
|
procedure GLRectangleBorder(const x1, y1, x2, y2: TGLfloat; const Color: TVector4f; const BorderWidth: Single = 1.0); overload; |
Draw rectangle border.
The vertex order is the same as for glRectf, so it's CCW from standard view. Changes OpenGL current color and line width.
|
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 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 GLFadeRectangle(const X1, Y1, X2, Y2: Integer; const FadeColor: TVector3Single; const FadeIntensity: Single); |
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.
The rectangle is affected by current modelview matrix. Requires one attrib stack place.
|
procedure GLBlendRectangle(const X1, Y1, X2, Y2: Integer; const SourceFactor, DestinationFactor: TGLenum; const Color: TVector4Single); |
Draw a rectangle with blending.
The rectangle is affected by current modelview matrix. Requires one attrib stack place.
|
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 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 bitmap fonts) with lower-left corner in the X,Y pixel.
For OpenGL versions that have a concept of a "raster" (not present in OpenGL ES) this sets raster position in window coordinates. Such that the raster position is never clipped. In this case this is similar to just calling glWindowPos, and actually will simply call glWindowPos if available (if OpenGL version is adequate, or equivalent OpenGL extension is available).
The depth value of raster is undefined after calling this. This is necessary, in case of old OpenGL with no glWindowPos extension, where we do a little trick to similate glWindowPos. It should not be a problem if you only use this to draw simple 2D GUI stuff.
|
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. |
procedure glColorOpacity(const Color: TVector3Single; const Opacity: Single); |
Call glColor, taking Opacity as separate Single argument.
|
procedure glColorOpacity(const Color: TVector3Byte; const Opacity: Single); |
|
function GLEnableTexture(const Target: TEnableTextureTarget): boolean; |
Enable exactly one (or none, for Target=etNone) OpenGL texture target. 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.
|
Types
TGLSupport = (...); |
Values
-
gsNone:
-
gsExtension:
-
gsStandard:
|
TGLbitfield = GLbitfield; |
|
TDepthRange = (...); |
Values
|
TEnableTextureTarget = (...); |
Values
-
etNone:
-
et2D:
-
etCubeMap:
-
et3D:
-
etRectangle:
|
Constants
GLSupportNames: array [TGLSupport] of string =
( 'None', 'Extension', 'Standard' ); |
|
Variables
glListIBase: procedure(base: TGLint); cdecl; |
Equivalent to glListBase but it's parameter is a signed integer.
Original declararations of glListBase take unsigned integer, while actually a signed integer is also allowed. Actually, you should always call gListBase with range/overflow checking turned off. That's because argument to glListBase is used by OpenGL only in an expression like
Base + CurrentListNumber
so it's the "CurrentListNumber" that determines what Base actually means — e.g. if Base = LongWord(-100) and CurrentListNumber = 1000 then the actual list number is 900, and this is all that matters. So you can say that Base was nagative. But if Base = LongWord(-100) and CurrentListNumber = 0 then the actual list number is LongWord(-100) = <some big integer around 4 * 10ˆ9>. So you can say that Base was positive.
|
Generated by PasDoc 0.13.0 on 2013-08-17 21:27:12
|