Differences

This shows you the differences between two versions of the page.

--- assetsmanager [2019/03/08 12:15] – created admin
+++ assetsmanager [2020/11/06 13:48] – [Groups] admin
@@ Line 1: / Line 1: @@
 ====== Using AssetsManager ======
+{{:assets.jpg?nolink|}}
 The AssetsManager is the core component in effective media management inside your Gorilla3D application.
+Models, textures, audio, dialogues and so on will be cached for faster access and reusage.
-Models, textures, audio and so on will be cached for faster access and reusage. You can build packages within the AssetsManager for modular media management.
+You can build packages within the AssetsManager for modular media management.
+For example: you could build a package for the main character and reference to it in every scene package.
-For example: you could build a package for the main character and reference to it in every scene package. Scene packages are extremly useful for compact and fast loading of all data of a specific scene.
+Scene packages are extremly useful for compact and fast loading of all data in a scene.
 ===== Package =====
+An assets package is the management unit to handle groups and their attached assets.
+It is allowed to store a package as zip-archive or to use as in-memory package.
 ===== Groups =====
-To organize media content the package provides a number of default groups for assets: models, textures, audio, video, misc, dialogue, inventory.
+Each package provides a number of fixed group entries to organize media content.
+Default group ids to access the specific group of each package:
+^ Group-ID   ^ Extensions ^
+| GORILLA_ASSETS_MODEL         | *.obj, *.g3d, *.dae, *.stl, *.x3d, *.x3dvz, *.x3dz, *.fbx, *.gltf, *.babylon |
+| GORILLA_ASSETS_TEXTURE      | *.bmp, *.jpg, *.jpeg, *.dds, *.gif, *.png, *.tif, *.tiff, *.tga |
+| GORILLA_ASSETS_AUDIO          | *.aiff, *.asf, *.asx, *.dls, *.flac, *.fsb, *.it, *.m3u, *.midi, *.mod, *.mp2, *.mp3, *.ogg, *.pls, *.s3m, *.vag, *.wav, *.wax, *.wma, *.xm, *.xma (FMOD Support activated) |
+| GORILLA_ASSETS_VIDEO           | *.mp4, *.mpg and *.mpeg |
+| GORILLA_ASSETS_MISC              | *.txt, *.json, *.xml |
+| GORILLA_ASSETS_DIALOGUE   | *.dia, *.dlg|
+| GORILLA_ASSETS_INVENTORY | *.iff |
 ===== Assets =====
-  A media file is represented as TGorillaAsset instance inside of a specific group in the assets package.
+A media file is represented as extended TGorillaAsset instance inside in a specific group in an assets package.
+Depending on the media type the asset holds the data.
-  The common media types are listed here:
+==== TGorillaModelAsset ====
-  * GORILLA_ASSETS_MODEL
+Holds model and animation data by the internal definition format TModelDef and writes data as *.g3d file to the zip-archive.
-  * GORILLA_ASSETS_TEXTURE
-  * GORILLA_ASSETS_AUDIO
+==== TGorillaTextureAsset ====
-  * GORILLA_ASSETS_VIDEO
+Holds the texture as TBitmap in memory and writes those in original file format to zip-archive.
-  * GORILLA_ASSETS_MISC
-  * GORILLA_ASSETS_DIALOGUE
+==== TGorillaAudioAsset ====
-  * GORILLA_ASSETS_INVENTORY
+Holds audio files in a TMemoryStream and writes those in original file format to zip-archive.
+==== TGorillaVideoAsset ====
+Holds video files in a TMemoryStream and writes those in original file format to zip-archive.
+==== TGorillaMiscAsset ====
+Used for unspecified file formats. Currently supported *.txt, *.json and *.xml.
+Holds data in a TMemoryStream and writes those in original file format to zip-archive.
+==== TGorillaDialogueAsset ====
+Holds dialogue data in a TMemoryStream and writes those as *.dia file to zip-archive.
+==== TGorillaInventoryAsset ====
+Holds inventory configuration data in a TMemoryStream and writes those as *.iff file to zip-archive.
 ===== DesignTime =====
@@ Line 31: / Line 59: @@
 ===== Example =====
+==== Creating package at runtime ====
 Alternatively you can create the assets manager and packages at runtime.
 <file pascal Form1.pas>
+var
+  FAssetsManager : TGorillaAssetsManager;
+  FPackage : TGorillaAssetsPackage;
+procedure TForm1.CreatePackage();
+begin
   FAssetsManager := TGorillaAssetsManager.Create(Self);
-  FAssetsManager.AddEmptyPackage(GORILLA_PACKAGE_DEFAULT);
+  FPackage := FAssetsManager.AddEmptyPackage(GORILLA_PACKAGE_DEFAULT);
+end;
+</file>
+==== Loading package from file ====
+You can easily setup packages by the Gorilla3D assets manager tool.
+There you can also save packages to file, which can be loaded at runtime in your program.
+<file pascal Form1.pas>
+procedure TForm1.LoadPackage(const AFilename : String);
+begin
+  FAssetsManager := TGorillaAssetsManager.Create(Self);
+  FPackage := FAssetsManager.LoadPackageFromFile(AFilename);
+end;
+</file>
+==== Storing your assets package at runtime ====
+Of course you are allowed to store the assets package you've setup.
+Easily use the provided SaveToFile method of each package instance.
+<file pascal Form1.pas>
+procedure TForm1.SavePackage(const AFilename : String);
+begin
+  FPackage.SaveToFile(AFilename);
+end;
+</file>
+==== Finding an asset inside of a package ====
+) Each assets has an unique id (GUID) when added to the package by which we can find it exactly.
+<file pascal Form1.pas>
+  // finding an asset in a specific group by its unique id
+  LAssetId := '{18E01973-D452-4596-A1A1-C51F09763954}';
+  FPackage.GetAssetFromId(GORILLA_ASSETS_TEXTURE, LAssetId);
+</file>
+) Get asset by its filename
+**Caution: This method will automatically import the asset from supplied file, if it can not be found.**
+<file pascal Form1.pas>
+  // finding an asset in a specific group by its filename
+  LAssetFile := 'texture0.png';
+  FPackage.GetAssetFromFile(GORILLA_ASSETS_TEXTURE, LAssetFile);
+</file>
+) Get asset by its filename and stream
+**Caution: This method will automatically import the asset from supplied stream, if it can not be found.**
+<file pascal Form1.pas>
+  // finding an asset in a specific group by its filename
+  LAssetFile := 'texture0.png';
+  FPackage.GetAssetFromStream(GORILLA_ASSETS_TEXTURE, LAssetFile, AStream);
 </file>
+Next step: [[billboard|Billboard]]