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 internal bake module follows while to writing the .pak:

1. Open the .toml project file specified on the command line
2. Parse each contained .toml asset file reference, and any additional references they may lead to
3. Store all data (vertices, pixels, language strings, scene references, etc...) using the bincode library
4. 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 the optional compression field is brotli, [content] will accept these additional fields:

• 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

Model animations (.gltf or .glb only) 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]

[[model.mesh]]
src_name = 'ArtForChuck2021Version2_Plasma_Grenade_Pin'
dst_name = 'pin'

Details:

• offset: Optional.
• scale: Optional.
• [[model.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.

Modules

id	Types for keeping track of .pak resources.

Structs

MaterialDesc	Holds bitmap IDs to match what was setup in the asset .toml file.
Pak	A wrapper type which allows callers to specify the Read and Seek implementations used to read assets.
Ref	An individual Scene reference.
RefIter	An Iterator of SceneRef items.
Scene	A container for Ref references.

Enums

BitmapFormat

Describes the channels of a Bitmap.