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

  1. 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.

  2. Serialization: All definition types support JSON serialization via ToJSON/FromJSON methods. Binary serialization uses BSON format (G3D files).

  3. Caching: Animation caching significantly improves playback performance. Use VertexPosition flag for best balance.

  4. Index Format: Platform-dependent (UInt32 on desktop, UInt16 on Android) for memory optimization.

  5. Texture Limits: Essential for mobile platforms to prevent memory exhaustion from high-resolution textures.

  6. Extensions: Material extensions (PBR, custom properties) stored in TExtensionDefList for format compatibility.

See Also