mirror of
https://github.com/odin-lang/Odin.git
synced 2025-12-29 01:14:40 +00:00
83 lines
5.2 KiB
Odin
83 lines
5.2 KiB
Odin
// Implementation of the HxA 3D asset format
|
|
// HxA is a interchangeable graphics asset format.
|
|
// Designed by Eskil Steenberg. @quelsolaar / eskil 'at' obsession 'dot' se / www.quelsolaar.com
|
|
//
|
|
// Author of this Odin package: Ginger Bill
|
|
//
|
|
// Following comment is copied from the original C-implementation
|
|
// ---------
|
|
// -Does the world need another Graphics file format?
|
|
// Unfortunately, Yes. All existing formats are either too large and complicated to be implemented from
|
|
// scratch, or don't have some basic features needed in modern computer graphics.
|
|
// -Who is this format for?
|
|
// For people who want a capable open Graphics format that can be implemented from scratch in
|
|
// a few hours. It is ideal for graphics researchers, game developers or other people who
|
|
// wants to build custom graphics pipelines. Given how easy it is to parse and write, it
|
|
// should be easy to write utilities that process assets to preform tasks like: generating
|
|
// normals, light-maps, tangent spaces, Error detection, GPU optimization, LOD generation,
|
|
// and UV mapping.
|
|
// -Why store images in the format when there are so many good image formats already?
|
|
// Yes there are, but only for 2D RGB/RGBA images. A lot of computer graphics rendering rely
|
|
// on 1D, 3D, cube, multilayer, multi channel, floating point bitmap buffers. There almost no
|
|
// formats for this kind of data. Also 3D files that reference separate image files rely on
|
|
// file paths, and this often creates issues when the assets are moved. By including the
|
|
// texture data in the files directly the assets become self contained.
|
|
// -Why doesn't the format support <insert whatever>?
|
|
// Because the entire point is to make a format that can be implemented. Features like NURBSs,
|
|
// Construction history, or BSP trees would make the format too large to serve its purpose.
|
|
// The facilities of the formats to store meta data should make the format flexible enough
|
|
// for most uses. Adding HxA support should be something anyone can do in a days work.
|
|
//
|
|
// Structure:
|
|
// ----------
|
|
// HxA is designed to be extremely simple to parse, and is therefore based around conventions. It has
|
|
// a few basic structures, and depending on how they are used they mean different things. This means
|
|
// that you can implement a tool that loads the entire file, modifies the parts it cares about and
|
|
// leaves the rest intact. It is also possible to write a tool that makes all data in the file
|
|
// editable without the need to understand its use. It is also possible for anyone to use the format
|
|
// to store data axillary data. Anyone who wants to store data not covered by a convention can submit
|
|
// a convention to extend the format. There should never be a convention for storing the same data in
|
|
// two differed ways.
|
|
// The data is story in a number of nodes that are stored in an array. Each node stores an array of
|
|
// meta data. Meta data can describe anything you want, and a lot of conventions will use meta data
|
|
// to store additional information, for things like transforms, lights, shaders and animation.
|
|
// Data for Vertices, Corners, Faces, and Pixels are stored in named layer stacks. Each stack consists
|
|
// of a number of named layers. All layers in the stack have the same number of elements. Each layer
|
|
// describes one property of the primitive. Each layer can have multiple channels and each layer can
|
|
// store data of a different type.
|
|
//
|
|
// HaX stores 3 kinds of nodes
|
|
// - Pixel data.
|
|
// - Polygon geometry data.
|
|
// - Meta data only.
|
|
//
|
|
// Pixel Nodes stores pixels in a layer stack. A layer may store things like Albedo, Roughness,
|
|
// Reflectance, Light maps, Masks, Normal maps, and Displacement. Layers use the channels of the
|
|
// layers to store things like color. The length of the layer stack is determined by the type and
|
|
// dimensions stored in the
|
|
//
|
|
// Geometry data is stored in 3 separate layer stacks for: vertex data, corner data and face data. The
|
|
// vertex data stores things like verities, blend shapes, weight maps, and vertex colors. The first
|
|
// layer in a vertex stack has to be a 3 channel layer named "position" describing the base position
|
|
// of the vertices. The corner stack describes data per corner or edge of the polygons. It can be used
|
|
// for things like UV, normals, and adjacency. The first layer in a corner stack has to be a 1 channel
|
|
// integer layer named "index" describing the vertices used to form polygons. The last value in each
|
|
// polygon has a negative - 1 index to indicate the end of the polygon.
|
|
//
|
|
// Example:
|
|
// A quad and a tri with the vertex index:
|
|
// [0, 1, 2, 3] [1, 4, 2]
|
|
// is stored:
|
|
// [0, 1, 2, -4, 1, 4, -3]
|
|
// The face stack stores values per face. the length of the face stack has to match the number of
|
|
// negative values in the index layer in the corner stack. The face stack can be used to store things
|
|
// like material index.
|
|
//
|
|
// Storage
|
|
// -------
|
|
// All data is stored in little endian byte order with no padding. The layout mirrors the structs
|
|
// defined below with a few exceptions. All names are stored as a 8-bit unsigned integer indicating
|
|
// the length of the name followed by that many characters. Termination is not stored in the file.
|
|
// Text strings stored in meta data are stored the same way as names, but instead of a 8-bit unsigned
|
|
// integer a 32-bit unsigned integer is used.
|
|
package encoding_hxa |