From bd2f74b120891867325309b9c37d43541b8244f3 Mon Sep 17 00:00:00 2001 From: light7734 Date: Wed, 6 Aug 2025 12:11:03 +0330 Subject: [PATCH] docs: minor changes to architecture/assets --- docs/architecture/assets.rst | 66 +++++++++++++++++++++--------------- 1 file changed, 38 insertions(+), 28 deletions(-) diff --git a/docs/architecture/assets.rst b/docs/architecture/assets.rst index 9bb6709..eb40b70 100644 --- a/docs/architecture/assets.rst +++ b/docs/architecture/assets.rst @@ -1,62 +1,72 @@ Asset Management =================================================================================================== -Layout + +On Disk (file) Layout --------------------------------------------------------------------------------------------------- -{version} | 4 bytes, ie. uint32_t -{general metadata} | sizeof(AssetMetadata) -{specialized metadata} | sizeof(XXXAssetMetadata), eg. TextureAssetMetadata -{n} | 4 bytes, ie. uint32_t -{blob_0...n metadata} | n * sizeof(BlobMetadata) -{blob_0...n data} | variable size based on actual data -{end marker} | 8 byte, ie size_t for marking the END + +.. code-block:: md + + {version} | 4 bytes, ie. uint32_t + {general metadata} | sizeof(AssetMetadata) + {specialized metadata} | sizeof(XXXAssetMetadata), eg. TextureAssetMetadata + {n} | 4 bytes, ie. uint32_t + {blob_0...n metadata} | n * sizeof(BlobMetadata) + {blob_0...n data} | variable size based on actual data + {end marker} | 8 byte, ie size_t for marking the END Sections --------------------------------------------------------------------------------------------------- -version -> The version of the asset for forward compatibility -general metadata -> Common asset metadata such as file-path, asset-type, creator, etc. -specialized metadata -> Metadata specific to the asset, eg. texture dimensions for Textures. -n -> The number of blobs. -blob_0...n metadata -> Metadata specifying how the actual data is packed, required for unpacking. -blob_0...n data -> The actual data, packed and compressed to be reacdy for direct engine consumption. + +.. code-block:: md + + version -> The version of the asset for forward compatibility + general metadata -> Common asset metadata such as file-path, asset-type, creator, etc. + specialized metadata -> Metadata specific to the asset, eg. texture dimensions for Textures. + n -> The number of blobs. + blob_0...n metadata -> Metadata specifying how the actual data is packed, required for unpacking. + blob_0...n data -> The actual data, packed and compressed to be reacdy for direct engine consumption. Loading --------------------------------------------------------------------------------------------------- -Each `Loader` has ONE OR MORE supported input file types (detected via the file extension): eg. StbLoader -> Can read in .jpg, .png, .bmp, etc.... files +Loading pre-baked asset files (like .png files) for baking: -Each `Loader` has ONLY ONE supported output asset type: + +Each **Loader** has ONE OR MORE supported input file types (detected via the file extension): eg. StbLoader -> Can read in .jpg, .png, .bmp, etc.... files + +Each **Loader** has ONLY ONE supported output asset type: eg. StbLoader -> outputs TextureAsset -Multiple `Loader`s MAY have as output the same asset type: +Multiple **Loader**\s MAY have as output the same asset type: eg. StbLoader -> outputs TextureAsset eg. SomeOtherImgLoader -> outputs TextureAsset -Multiple `Loader`s SHOULD NOT have as input same extension types -eg. .jpg, .png -> if supported, should only be supported by 1 `Loader` class +Multiple **Loader**\s SHOULD NOT have as input same extension types +eg. .jpg, .png -> if supported, should only be supported by 1 **Loader** class -Each `Loader` SHOULD read and turn the data from a file (eg. .png for textures) into something -understandable by a `Packer` (not the engine itself). +Each **Loader** SHOULD read and turn the data from a file (eg. .png for textures) into something +understandable by a **Packer** (not the engine itself). -A `Loader` SHOULD NOT be responsible for packing the parsed file data into asset data, +A **Loader** SHOULD NOT be responsible for packing the parsed file data into asset data, as that implies direct understanding of the layout required by the engine. -And if that layout changes, ALL `Loader`s should change accordingly; +And if that layout changes, ALL **Loader**s should change accordingly; which makes a class that's responsible for reading files dependant on the engine's (potentially frequent) internal changes. -The logic is to reduce many-to-one dependency into a one-to-one dependency by redirecting the packing process to `Packer` classes +The logic is to reduce many-to-one dependency into a one-to-one dependency by redirecting the packing process to **Packer** classes Packing --------------------------------------------------------------------------------------------------- -Each `Packer` is responsible for packing ONLY ONE asset type: +Each **Packer** is responsible for packing ONLY ONE asset type: eg. TexturePacker for packing texture assets from parsed image files. eg. ModelPacker for packing model assets from parsed model files. -Each `Packer` will output ONE OR MORE blobs of data, +Each **Packer** will output ONE OR MORE blobs of data, and for EACH blob of data, it'll write a BlobMetadata, AFTER the specialized metadata (eg. TextureAssetMetadata) -A `Packer` will make use of the `Compressor` classes to compress the data, +A **Packer** will make use of the **Compressor** classes to compress the data, and lay it out in a way that is suitable for the engine's consumption. Unpacking --------------------------------------------------------------------------------------------------- -A `Parser` is responsible for parsing ONLY ONE asset type: +A **Parser** is responsible for parsing ONLY ONE asset type: eg. TextureParser for parsing texture assets for direct engine consumption. eg. ModelParser for parsing model assets for direct engine consumption.