[−][src]Module screen_13::pak

Types which support the .pak file format and general serialization functionality.

Overview

Programs which require the smallest download sizes and the fastest runtimes are incompatible with existing file formats, including .gltf. In order to provide the best asset compression and fastest load times Screen 13 implements a bespoke serialization engine.

NOTE: Basic encoding and compression has been implemented for all types; however bitmaps in particular have a lot of additional features to go. Hardware texture compression and perceptual encoding such as storing some bitmaps in 4:2:0 is still todo.

The `.pak` File Format

Using the baking process described in the main README, we are able to run the Screen 13 executable and produce .pak files. It may help to know more about the processes the bake module follow while to writing the .pak:

Open the .toml project file specified on the command line
Parse each contained .toml asset file reference, and any additional references they may lead to
Store all data (vertices, pixels, language strings, scene references, etc...) using the bincode library
Optionally compress the bincode data using either brotli or snap

Technical `.pak` Notes

Due to the repetitive nature of the pixel and vertex assets commonly used in games and simulations, data compression seems particularly effective. Expect 10:1 typical data compression when using default settings, or more when tweaked to the workload.

To further reduce data storage, vertex NORMAL and TANGENT attributes are not stored as file data but instead calculated at runtime, using compute hardware.

Project File (`.toml` format)

The main project file, which is required in order to bake content, looks like:

[content]
compression = 'brotli' | 'snap'
  
[[content.group]]
assets = [
    "directory/file.ext",
    "another.ext",
    ...
]

The [[content.group]] section may be repeated and may contain an enabled boolean value to make development and debugging easier.

Each file referenced in the project file, and all other .toml asset files, is referenced relative to the directory of the main project file. This means absolute references inside the project file and other assets files will resolve somewhere within the directory containing the project .toml file. Similarly, relative file references are evaluated with respect to the actual project-directory location in which the references are made.

NOTE: When compression is brotli, [content] will accept these additional integer settings:

buf_size: Default is 4096 if not specified
quality: Default is 10 if not specified
window_size: Default is 20 if not specified

Keys

All asset files referenced within a project file resolve to a path somewhere within the virtual directory structure created by a project, and this final location (minus file extension) is referred to as an assets' key.

This means that no matter how it is referenced, a file at img/blast_marks.toml will get the key img/blast_marks and it will only be imported once. These keys are used with the read_ functions of Gpu, in addition to other places.

Animations

.gltf or .glb model animations may be imported using an animation .toml file:

[animation]
src = 'anims/peggy.glb'
name = 'Pirate Idle 01'
exclude = ['right_leg', 'right_foot'] // <-- 🏴‍☠️

Optional fields:

name: Specifies the named animation to import from the source file.
exclude: Specifies bones which will not be imported.

Bitmapped Fonts

Right now only .fnt files (BMFont tested, others exist and may work) are supported. The file contains a src reference only:

[bitmap-font]
src = '../art/late/font copy (1).fnt'

Bitmaps

Loading images is pretty simple:

[bitmap]
src = 'images/42.png'
format = 'rgb'

Optional field:

format: Accepts r, rg, rgb or rgba. Down converts the source in order to produce a bitmap with only the required channels.

Materials

Materials are used while rendering models as Screen 13 does not retain an material information stored in the model source file, other than texture coordinates.

[material]
color = 'color_asset.toml'
metal_src = 'metalness.png'
normal = 'normal_asset.toml'
rough_src = 'roughness.png'

Fields:

color: A bitmap asset .toml file for the albedo/diffuse map. (the texture)
metal_src: An image file to use for the PBR metalness parameters; reads R channel only.
normal: A bitmap asset .toml file for the normal map.
rough_src: An image file to use for the PBR roughness parameters; reads R channel only.

Models

Three dimensional models (.gltf or .glb only) are loaded using a model asset file:

[model]
src = 'plasma_grenade.glb`
offset = [0, 0, 0]
scale = [1, 1, 1]
 
[[mesh]]
src_name = 'ArtForChuck2021Version2_Plasma_Grenade_Pin'
dst_name = 'pin'

Details:

offset: Optional.
scale: Optional.
[[mesh]]: Optional. May be repeated. Describes the subset of meshes to be imported, if specified.
src_name: The artist-defined mesh name from within the source model file.
dst_name: Optional. The remapped name to import this mesh with. Mesh name is removed if not specified.

Scenes

Complex scenes may be stored in scene asset .toml files:

[scene]
 
[[scene.ref]]
id = 'power-up-001'
model = 'power-up.toml'
material = 'glossy.toml`
position = [0, 0, 0]
rotation = [180, 0, 0]
tags = ['health', 'special']

Optional tags and fields:

[[scene.ref]]: May be repeated. Defines a location of some importance.
id: A unique ID used to refer to a scene reference.
model: A model asset file to reference.
material: A material asset file to reference.
position: Any Vec3 position.
rotation: Specified as degrees in pitch, yaw, roll format.
tags: An array of strings to attach to a scene reference.

NOTE: The scene baking code uses a string table to avoid needless duplicates being stored in the .pak file. Compression additionally reduces the burden of dense/complicated scenes.

Using `.pak` Files at Runtime

.pak files may be opened using the Pak type, and may be dropped as soon as the required resources have been read using the Gpu::read_... functions.

Structs

Animation	Holds an `Animation` in a `.pak` file. For data transport only.
AnimationId	An identifier for `Animation` instances which is unique within one `.pak` file.
Bitmap	Holds a `Bitmap` in a `.pak` file. For data transport only.
BitmapFont	Holds a `BitmapFont` in a `.pak` file. For data transport only.
BitmapFontId	An identifier for `BitmapFont` instances which is unique within one `.pak` file.
BitmapId	An identifier for `Bitmap` instances which is unique within one `.pak` file.
BlobId	An identifier for byte array instances which is unique within one `.pak` file.
Channel	Describes the animation of one joint.
Material	Holds bitmap IDs to match what was setup in the asset `.toml` file.
MaterialId	An identifier for `Material` instances which is unique within one `.pak` file.
ModelId	An identifier for `Model` instances which is unique within one `.pak` file.
Pak	A wrapper type which allows callers to specify the `Read` and `Seek` implementations used to read assets.
PakBuf	Main serialization container for the `.pak` file format.
Scene	A container for references.
SceneId	An identifier for `Scene` instances which is unique within one `.pak` file.
TextId	An identifier for text fragments which is unique within one `.pak` file.

Enums

BitmapFormat	Describes the channels of a `Bitmap`.
ErrorKind	The kind of error that can be produced during a serialization or deserialization.