Unit CastleRenderer

Description

VRML / X3D low-level rendering (TGLRenderer). You should never use this renderer directly, you should always use TCastleScene that wraps this renderer and gives you simple method to render whole scene. TODO: this unit should be renamed to Internal at some point.

The overview of the renderer can also be found in engine documentation [https://castle-engine.io/engine_doc.php] in chapter "OpenGL rendering", section "Basic OpenGL rendering".

Usage:

  1. Call TGLRenderer.Prepare for all the states that you want to later render. The order of calling TGLRenderer.Prepare methods doesn't matter, also you are free to prepare states that you will not actually use later. Of course a state, once prepared, may be used in rendering as many times as you want.

    It's important that you have to prepare every state that you plan to later render. During rendring the state must have exactly the same (fields, properties) values as when it was prepared. In particular, it must have the same pointers to nodes Last*/Active* and their contents also must be the same. TGLRenderer.Prepare may save some associations between objects and OpenGL resources, so it's important that the same pointer must always point to the same object (until it's unprepared).

    TGLRenderer.Prepare requires active OpenGL context. It doesn't modify OpenGL state (only allocates some resources like texture names). It cannot be called inside a display list.

  2. When you want to release resources, you should call TGLRenderer.Unprepare on nodes that you want to change or free. This should be used with nodes that were passed as Last*/Active* in some State for TGLRenderer.Prepare.

    Note that you cannot free the nodes before unpreparing them. The node instance must remain valid while it's prepared.

  3. To start actual rendering, call TGLRenderer.RenderBegin. To end rendering, call TGLRenderer.RenderEnd. Between these calls, you should not touch OpenGL state yourself — the renderer may depend that every state change goes through it. At the end of TGLRenderer.RenderEnd, the OpenGL state is restored just as it was before TGLRenderer.RenderBegin.

  4. Between TGLRenderer.RenderBegin and TGLRenderer.RenderEnd you should render the shapes by calling RenderShape.

    Remember that you can render only shapes that have Shape.State prepared by TGLRenderer.Prepare.

  5. Since the first prepare / render calls, this renderer assumes it's always called in the same OpenGL context. To break association with OpenGL context call TGLRenderer.UnprepareAll (this is like calling TGLRenderer.Unprepare on every prepared thing + clearing some remaining resources).

OpenGL state affecting VRML rendering:

Some OpenGL state is unconditionally reset by TGLRenderer.RenderBegin.

There's also some OpenGL state that we let affect our rendering. This allows you to customize rendering by using normal OpenGL commands.

  • Current glPolygonMode. This is used by TCastleScene to optionally render wireframe.

  • Blending settings (GL_BLEND enabled state, glBlendFunc), and glDepthMask.

    This is used by TCastleScene to render scenes with a mix of tranparent and opaque objects. Only TCastleScene deals with it (not this renderer), as doing it correctly requires ordering the shapes.

The renderer uses arrays in GPU-friendly format defined by TGeometryArrays.

They have the same number of triangles and vertices as calculated by TAbstractGeometryNode.Triangulate, TAbstractGeometryNode.LocalTriangulate, TAbstractGeometryNode.TrianglesCount, TAbstractGeometryNode.VerticesCount (with OverTriangulate = True).

Uses

Overview

Classes, Interfaces, Objects and Records

Name Description
Class TRenderingAttributes Various properties that control rendering.
Class TTextureImageCache  
Class TTextureVideoCache  
Class TTextureCubeMapCache  
Class TTexture3DCache  
Class TTextureDepthOrFloatCache Cached depth or float texture.
Class TShapeCache Cached shape resources.
Class TShaderProgramCache  
Class TGLRendererContextCache Cache used by TGLRenderer instances to share OpenGL resources, like textures.
Class TResourceRenderer Base class for TGLRenderer helper.
Class TResourceRendererList  
Class TGLTextureNode OpenGL handling for VRML/X3D texture node.
Class TGLTextureNodes  
Class TGLSingleTextureNode Common class for all single (not multi-texture) texture nodes.
Class TGLMultiTextureNode Handler for TMultiTextureNode.
Class TGL2DTextureNode Handler for 2D textures that have a corresponding OpenGL resource.
Class TGLImageTextureNode Handler for TAbstractTexture2DNode with image (not a video).
Class TGLMovieTextureNode  
Class TGLRenderedTextureNode  
Class TGLCubeMapTextureNode Common handling for texture nodes of TAbstractEnvironmentTextureNode.
Class TGLComposedCubeMapTextureNode  
Class TGLImageCubeMapTextureNode  
Class TGLGeneratedCubeMapTextureNode  
Class TGL3DTextureNode  
Class TGLGeneratedShadowMap  
Class TGLShaderTexture  
Class TX3DGLSLProgram GLSL program integrated with VRML/X3D renderer.
Class TX3DRendererShape Shape that can be rendered.
Class TGLRenderer  

Types

TBeforeGLVertexProc = procedure (Node: TAbstractGeometryNode; const Vert: TVector3) of object;
TShadersRendering = (...);
TBumpMapping = CastleRendererInternalShader.TBumpMapping;
TLightRenderEvent = CastleRendererInternalLights.TLightRenderEvent;
TRenderingMode = (...);
TRenderingAttributesClass = class of TRenderingAttributes;
TTextureImageCacheList = specialize TObjectList<TTextureImageCache>;
TTextureVideoCacheList = specialize TObjectList<TTextureVideoCache>;
TTextureCubeMapCacheList = specialize TObjectList<TTextureCubeMapCache>;
TTexture3DCacheList = specialize TObjectList<TTexture3DCache>;
TTextureDepthOrFloatCacheList = specialize TObjectList<TTextureDepthOrFloatCache>;
TVboType = (...);
TVboTypes = set of TVboType;
TVboArrays = array [TVboType] of TGLuint;
TShapeCacheList = specialize TObjectList<TShapeCache>;
TShaderProgramCacheList = specialize TObjectList<TShaderProgramCache>;
TGLTextureNodeClass = class of TGLTextureNode;

Constants

AllVboTypes = [Low(TVboType) .. High(TVboType)];
BumpMappingNames: array [TBumpMapping] of string = ( 'None', 'Basic', 'Parallax', 'Steep Parallax', 'Steep Parallax With Self-Shadowing' );
rmPureGeometry = rmSolidColor deprecated 'use rmSolidColor';

Variables

LogRendererCache: boolean = false;
LogRenderer: boolean = false;

Description

Types

TBeforeGLVertexProc = procedure (Node: TAbstractGeometryNode; const Vert: TVector3) of object;
 
TShadersRendering = (...);
 
Values
  • srDisable
  • srWhenRequired
  • srAlways
TBumpMapping = CastleRendererInternalShader.TBumpMapping;
 
TLightRenderEvent = CastleRendererInternalLights.TLightRenderEvent;
 
TRenderingMode = (...);

TRenderingAttributes.Mode possible values.

Values
  • rmFull: Normal rendering features. Everything is enabled (as long as other TRenderingAttributes settings allow them).
  • rmSolidColor: Solid color is used for everything. We do not show any color variation, materials, lights, fog, textures on surfaces. We still do back-face culling and depth test. The idea is that we "hit" the same pixels as normal rendering (with the exception of alpha test textures, this mode doesn't set up alpha test for them). But everything has color TRenderingAttributes.SolidColor.

    This is useful for special tricks.

  • rmDepth: Only the rendering fetures that affect depth buffer work reliably, everything else is undefined (and works as fast as possible). This is suitable if you render only to depth buffer, like for shadow maps.

    It's quite similar to rmSolidColor, except alpha testing must work, so (at least some) textures must be applied over the model.

TRenderingAttributesClass = class of TRenderingAttributes;
 
TTextureImageCacheList = specialize TObjectList<TTextureImageCache>;
 
TTextureVideoCacheList = specialize TObjectList<TTextureVideoCache>;
 
TTextureCubeMapCacheList = specialize TObjectList<TTextureCubeMapCache>;
 
TTexture3DCacheList = specialize TObjectList<TTexture3DCache>;
 
TTextureDepthOrFloatCacheList = specialize TObjectList<TTextureDepthOrFloatCache>;
 
TVboType = (...);
 
Values
  • vtCoordinate
  • vtAttribute
  • vtIndex
TVboTypes = set of TVboType;
 
TVboArrays = array [TVboType] of TGLuint;
 
TShapeCacheList = specialize TObjectList<TShapeCache>;
 
TShaderProgramCacheList = specialize TObjectList<TShaderProgramCache>;
 
TGLTextureNodeClass = class of TGLTextureNode;
 

Constants

AllVboTypes = [Low(TVboType) .. High(TVboType)];
 
BumpMappingNames: array [TBumpMapping] of string = ( 'None', 'Basic', 'Parallax', 'Steep Parallax', 'Steep Parallax With Self-Shadowing' );
 
rmPureGeometry = rmSolidColor deprecated 'use rmSolidColor';

Warning: this symbol is deprecated: use rmSolidColor

 

Variables

LogRendererCache: boolean = false;

Log renderer cache events. Allows to see how the cache performs. A lot of log messages.

Meaningful only if you initialized log (see CastleLog unit) by InitializeLog first.

LogRenderer: boolean = false;

Log various renderer information.

Meaningful only if you initialized log (see CastleLog unit) by InitializeLog first.


Generated by PasDoc 0.15.0.