Gorilla.DefTypes Unit Reference
Overview
The Gorilla.DefTypes unit provides fundamental definition types used throughout Gorilla3D for storing and managing 3D model data. It defines the internal structure for models, meshes, materials, textures, animations, and all related components. These definition classes serve as data containers that can be serialized to/from JSON or binary formats.
Architecture
The definition types implement a hierarchical structure for 3D model data:
TModelDef (Root)
├─ Children (Meshes, VertexGroups, Lights, Cameras, Segments, Groups)
├─ Materials (TMaterialDef)
├─ Lights (TLightDef)
├─ Cameras (TCameraDef)
├─ Armatures (TArmatureDef)
│ └─ Joints (TJointDef hierarchy)
├─ Controllers (TControllerDef)
│ └─ Skin (TSkinDef with joint references)
└─ Animations (TAnimationDef)
└─ Stages (TAnimationStageDef)
└─ Interpolators (TInterpolatorDef)
Core Constants
GORILLA_POLYGON_MAXSIZE = 16; // Maximum vertices per polygon
GORILLA_ARRAY_TEXTURE_MAX = 32; // Maximum texture layers
GORILLA_ARRAY_COLOR_MAX = 4; // Maximum color sets
GORILLA_MAX_JOINTS_PER_VERTEX = 24; // Maximum joint influences per vertex
GORILLA_CACHE_CAPACITY = High(UInt16); // Cache capacity (65535)
// Animation cache frame rates
GORILLA_ANIMATION_CACHE_FRAMERATE_24 = 24;
GORILLA_ANIMATION_CACHE_FRAMERATE_30 = 30;
GORILLA_ANIMATION_CACHE_FRAMERATE_60 = 60;
// Platform-specific defaults
{$IFDEF MSWINDOWS}
GORILLA_ANIMATION_CACHE_FRAMERATE = 60;
GORILLA_INDEX_FORMAT = TIndexFormat.UInt32;
{$ENDIF}
{$IFDEF ANDROID}
GORILLA_ANIMATION_CACHE_FRAMERATE = 24;
GORILLA_INDEX_FORMAT = TIndexFormat.UInt16;
{$ENDIF}
// ... other platforms
GORILLA_SEGMENT_ID_FORMAT = '%s_Seg'; // Segment ID format string
Base Types
TCustomDef
Base class for all definition types.
Properties
| Property | Type | Description |
|---|---|---|
| Id | String | Unique identifier for this definition. |
Methods
constructor Create(); virtual;
destructor Destroy(); override;
function Clone(AOwner: TModelDef): TCustomDef; virtual;
function GetSize(): Int64; virtual;
Returns memory size in bytes.
function GetAssetsPackage(): TObject; virtual;
Returns associated assets package.
function ToJSON(): TJSONObject; virtual;
procedure FromJSON(const AModel: TModelDef; const AValue: TJSONObject); virtual;
function LateResolveFromJSON(const AModel: TModelDef;
const AValue: TJSONObject): Boolean; virtual;
JSON serialization methods.
TModelDef
Root definition for complete 3D models. Contains all sub-components including meshes, materials, animations, lights, cameras, and armatures.
Inheritance: TCustomDef → TTransformDef → TModelDef
Properties
| Property | Type | Description |
|---|---|---|
| Children | TObjectList | List of child definitions (meshes, groups, etc.). |
| Materials | TObjectList<TMaterialDef> | List of material definitions. |
| Lights | TObjectList<TLightDef> | List of light definitions. |
| Cameras | TObjectList<TCameraDef> | List of camera definitions. |
| Armatures | TObjectList<TArmatureDef> | List of armature definitions. |
| Controllers | TObjectList<TControllerDef> | List of controller definitions for skinning. |
| Animations | TObjectList<TAnimationDef> | List of animation definitions. |
| MetaData | TModelMetaDef | Model metadata (title, author, license, etc.). |
| Package | TObject | Reference to assets package if stored in one. |
TMeshDef
Mesh geometry definition containing vertices, indices, and material references.
Inheritance: TCustomDef → TTransformDef → TCustomMeshDef → TMeshDef
Properties
| Property | Type | Description |
|---|---|---|
| Vertices | TArray<TVertexData> | Array of vertex data. |
| Indices | TArray<TIndexType> | Array of triangle indices. |
| Material | TMaterialDef | Reference to material definition. |
| IsStatic | Boolean | Indicates if mesh is static (prebuffered to GPU). |
| BoundingBox | TBoundingBox | Mesh bounding box. |
| Children | TObjectList | List of child meshes. |
TMaterialDef
Material definition with textures and properties.
Inheritance: TCustomDef → TMaterialDef
Properties
| Property | Type | Description |
|---|---|---|
| Textures | TObjectList<TTextureDef> | List of texture definitions. |
| Diffuse | TAlphaColorF | Diffuse color. |
| Ambient | TAlphaColorF | Ambient color. |
| Emissive | TAlphaColorF | Emissive color. |
| Specular | TAlphaColorF | Specular color. |
| Shininess | Single | Shininess factor. |
| Extensions | TExtensionDefList | List of extensions (PBR, etc.). |
Data Structures
TGorillaLoadOptions
Configuration structure for loading models with fine-grained control.
Fields
| Field | Type | Description |
|---|---|---|
| FileInfo | TGorillaFileInfo | File information (path, extension, URL, etc.). |
| Package | TObject of type TGorillaAssetsPackage |
Optional assets package of type. |
| Asset | TObject of type TGorillaModelAsset |
Optional model asset reference of type. |
| DisjointModel | Boolean | Load model with disjointed hierarchy. |
| ImportLights | Boolean | Import embedded lights. |
| ImportCameras | Boolean | Import embedded cameras. |
| ImportAnimations | Boolean | Import animations. |
| AdditionalAnimations | TArray<String> | Absolute paths to additional animation files. |
| Caching | TAnimationCachingFlags | Animation caching configuration. |
| VertexDataFlags | TVertexDataFlags | Vertex data processing flags. |
| OnStatus | TGorillaLoadingStatus = procedure(ALoader : TObject) of object; |
Status callback procedure. |
| ExtractDirectory | String | Directory for extracting downloads. |
| BitmapCache | TGorillaBitmapCache | Bitmap cache for textures. |
| TextureLimits | TPoint | Combined texture size limits. |
| Storage | TArray<TGorillaLoadStorage> | Storage for embedded file formats. |
Methods
constructor Create(APathOrUID: String; APackage: TObject = nil;
AAsset: TObject = nil); overload;
constructor Create(APathOrUID: String; AExt: String;
APackage: TObject = nil; AAsset: TObject = nil); overload;
constructor Create(APathOrUID: String; ACaching: TAnimationCachingFlags;
APackage: TObject = nil; AAsset: TObject = nil); overload;
function GetExtension(): String;
procedure SetExtension(const AValue: String);
procedure SetPathOrUID(const AValue: String);
function AddAnimation(const AFilename: String): Integer;
function AddStorage(const AName: String; const AStream: TStream): Integer;
function GetStorage(const AName: String): TStream;
procedure CopyTo(var ADest: TGorillaLoadOptions);
procedure Clear();
Example
var
Options: TGorillaLoadOptions;
begin
Options := TGorillaLoadOptions.Create('model.fbx', [], nil, nil);
// Configure loading
Options.ImportLights := True;
Options.ImportCameras := True;
Options.ImportAnimations := True;
Options.Caching := [TAnimationCachingFlag.VertexPosition];
Options.TextureLimits := TPoint.Create(2048, 2048);
// Add additional animations
Options.AddAnimation('walk.fbx');
Options.AddAnimation('run.fbx');
// Load model
MyModel.LoadFromFile(Options);
end;
TGorillaFileInfo
File information record for model loading.
Fields
| Field | Type | Description |
|---|---|---|
| PathOrUID | String | File path or unique identifier. |
| StrictFilename | Boolean | Require exact filename match in packages. |
| Ext | String | File extension for format detection. |
| OpenFormat | TGorillaFileOpenFormat | Local file or download mode. |
| OAuthMode | TGorillaOAuthMode | OAuth authentication mode (Sketchfab). |
| URL | String | Download URL. |
| Username | String | Login username for third-party systems. |
| Password | String | Login password. |
| ClientId | String | OAuth client ID. |
| ClientSecret | String | OAuth client secret. |
| AuthorizationEndpoint | String | Custom authorization endpoint URL. |
| AccessTokenEndpoint | String | Custom access token endpoint URL. |
| RedirectionEndpoint | String | Custom redirection endpoint URL. |
Methods
procedure CopyTo(var ADest: TGorillaFileInfo);
procedure Clear();
TVertexData
Vertex data record containing all vertex attributes.
Fields
| Field | Type | Description |
|---|---|---|
| Position | TPoint3D | Vertex position (XYZ coordinates). |
| Normal | TPoint3D | Normal vector. |
| Binormal | TPoint3D | Binormal vector (for normal mapping). |
| Tangent | TPoint3D | Tangent vector (for normal mapping). |
| TexCoords | TPointFDynArray | Texture coordinates (multiple layers). |
| Colors | TColorDynArray | Vertex colors (multiple sets). |
| SmoothGroup | Integer | Smooth group ID. |
| Flags | TVertexDataFlags | Processing flags. |
Methods
class function Create(): TVertexData; static;
procedure Clear();
function ToJSON(): TJSONObject;
procedure FromJSON(const AValue: TJSONObject);
function GetHash(): UInt64;
function Equals(const V: TVertexData): Boolean;
TTriangleRayCastResult
Ray casting intersection result.
Fields
| Field | Type | Description |
|---|---|---|
| T | Single | Distance along ray to intersection. |
| Normal | TPoint3D | Surface normal at intersection. |
| Hit | Boolean | True if intersection occurred. |
| Intersection | TPoint3D | Intersection point in 3D space. |
| Instance | TObject | Intersected object reference. |
| Triangle | Array[0..2] of TPoint3D | Triangle vertex positions. |
Enumerations
TAnimationCachingFlag
Animation caching configuration flags.
| Flag | Description |
|---|---|
| AllAttributes | Cache all vertex attributes (high memory, maximum speed). |
| Compressed | Compress cached data (lower memory, slower). |
| VertexPosition | Cache vertex positions only (recommended: balanced). |
Usage:
// Recommended: vertex positions only
[TAnimationCachingFlag.VertexPosition]
// Maximum performance
[TAnimationCachingFlag.AllAttributes]
// Compressed for large animations
[TAnimationCachingFlag.VertexPosition, TAnimationCachingFlag.Compressed]
TVertexDataFlag
Vertex data processing flags.
| Flag | Description |
|---|---|
| CalcNormals | Calculate normals. |
| CalcTangents | Calculate tangents and binormals. |
| CalcTexCoords | Calculate texture coordinates. |
| CalcSmoothNormals | Calculate smooth normals (averaged across faces). |
TColorChannelDef
Texture channel types for materials.
| Channel | Description |
|---|---|
| Diffuse | Diffuse/albedo map. |
| Ambient | Ambient occlusion map. |
| Emissive | Emissive/glow map. |
| Specular | Specular map. |
| Normal | Normal map (bump mapping). |
| Opacity | Opacity/transparency map. |
| Reflection | Reflection map. |
| Refraction | Refraction map. |
| Environment | Environment map. |
| Lightmap | Lightmap. |
| Displacement | Displacement map. |
| Metalness | Metalness map (PBR). |
| Roughness | Roughness map (PBR). |
| AO | Ambient occlusion (PBR). |
| HeightMap | Height map. |
| POM | Parallax occlusion map. |
| Depth | Depth map. |
| UserSpecific | Custom user channel. |
TGorillaFileOpenFormat
File opening mode.
| Value | Description |
|---|---|
| fofLocal | Load from local filesystem (default). |
| fofDownload | Download format (Sketchfab, etc.). |
TVertexOrder
Vertex winding order for triangles.
| Value | Description |
|---|---|
| CW | Clockwise vertex order [0, 2, 1]. |
| CCW | Counter-clockwise vertex order [1, 2, 0]. |
TFaceOrientation
Face culling mode.
| Value | Description |
|---|---|
| FrontFace | Render front faces only. |
| BackFace | Render back faces only. |
| TwoFace | Render both sides (no culling). |
Utility Classes
TGorillaBitmapCache
Collection for caching texture bitmaps at design-time.
Inheritance: TOwnedCollection → TGorillaBitmapCache
Methods
function FindBitmap(AFilename: String): TGorillaBitmapCacheEntry;
Finds cached bitmap by filename.
TGorillaBitmapCacheEntry
Individual cached bitmap entry.
Inheritance: TCollectionItem → TGorillaBitmapCacheEntry
Properties
| Property | Type | Description |
|---|---|---|
| Filename | String | Original filename of bitmap. |
| Bitmap | TBitmap | Bitmap data (embedded or referenced). |
TCacheList<T>
Memory-efficient list for caching with fixed-size growth steps.
Properties
| Property | Type | Description |
|---|---|---|
| Count | Integer | Number of items. |
| Steps | Integer | Growth step size. |
| Items[Index] | T | Access items by index. |
| List | TArray<T> | Internal array. |
Methods
function Add(AValue: T): Integer;
procedure AddRange(AArray: TArray<T>);
procedure Clear();
function ToArray(): TArray<T>;
function GetMemorySize(): Int64;
TProperties
Dictionary for storing extended properties.
Inheritance: TDictionary<String, TValue> → TProperties
Methods
function GetSize(): Int64;
procedure ToJSON(AJSON: TJSONObject);
procedure FromJSON(const AValue: TJSONObject);
Helper Types
// Dynamic arrays
TFloatDynArray = TArray<Single>;
TPoint3DDynArray = TArray<TPoint3D>;
TVector3DDynArray = TArray<TVector3D>;
TQuaternion3DDynArray = TArray<TQuaternion3D>;
TPointFDynArray = TArray<TPointF>;
TColorDynArray = TArray<TAlphaColorF>;
TMatrix3DDynArray = TArray<TMatrix3D>;
// Lists
TVertexDataList = class(TList<TVertexData>);
TIndexDataList = class(TList<TIndexType>);
TFaceIndexList = class(TList<TFaceIndex>);
// Maps
TVertexDataMap = TDictionary<TIndexType, TVertexData>;
Usage Examples
Creating Load Options
var
Options: TGorillaLoadOptions;
begin
// Basic options
Options := TGorillaLoadOptions.Create('character.dae', nil, nil);
// With caching
Options := TGorillaLoadOptions.Create('character.dae',
[TAnimationCachingFlag.VertexPosition], nil, nil);
// Advanced configuration
Options := TGorillaLoadOptions.Create('scene.fbx', [], MyPackage, nil);
Options.ImportLights := True;
Options.ImportCameras := True;
Options.TextureLimits := TPoint.Create(512, 512);
Options.AddAnimation('walk.fbx');
Options.AddAnimation('run.fbx');
end;
Working with Vertex Data
var
Vertex: TVertexData;
begin
Vertex := TVertexData.Create();
Vertex.Position := Point3D(1, 2, 3);
Vertex.Normal := Point3D(0, 1, 0);
// Add texture coordinates
SetLength(Vertex.TexCoords, 1);
Vertex.TexCoords[0] := PointF(0.5, 0.5);
// Add vertex color
SetLength(Vertex.Colors, 1);
Vertex.Colors[0] := TAlphaColorF.Create(1, 1, 1, 1);
end;
Using Bitmap Cache
var
Cache: TGorillaBitmapCache;
Entry: TGorillaBitmapCacheEntry;
begin
Cache := TGorillaBitmapCache.Create(Self, TGorillaBitmapCacheEntry);
// Find cached bitmap
Entry := Cache.FindBitmap('texture.png');
if Assigned(Entry) then
ShowMessage('Found: ' + Entry.Filename);
end;
Important Notes
-
Memory Management: Definition objects are typically owned by TGorillaAssetsManager when using packages. Standalone models own their definitions. So if a TModelDef/TMeshDef is destroyed all of its sub-meshes gets destroyed too.
-
Serialization: All definition types support JSON serialization via ToJSON/FromJSON methods. Binary serialization uses BSON format (G3D files).
-
Caching: Animation caching significantly improves playback performance. Use VertexPosition flag for best balance.
-
Index Format: Platform-dependent (UInt32 on desktop, UInt16 on Android) for memory optimization.
-
Texture Limits: Essential for mobile platforms to prevent memory exhaustion from high-resolution textures.
-
Extensions: Material extensions (PBR, custom properties) stored in TExtensionDefList for format compatibility.