entelechy-formatsGenerated

Layer: interface · Lines of code: 4,982 · Integration test files: 4

Brief

Entelechy file formats: PNG, PPM, WAV and base64, decoded to and encoded from Host Fields

Description

The codecs importer, exporter and session share: PNG, PPM, WAV and MIDI to and from Host Fields, a light’s IES photometry to one, the inflate PNG needs, base64, and the layouts of a font’s Fields. read and encode choose by a file’s extension. Each is pure bytes in, bytes or a Field out, depending on the Host alone.

A format belongs here when it decodes to a numerical Field, needs nothing outside the workspace, and is read live as a scene input. Application formats are read as bytes (read_bytes) and parsed by a Kernel; the rest are converted by entelechy-import or a bridge.


Internal dependencies	`entelechy-host`
External dependencies	—
Source	`crates/interface/formats`

Modules

Name	Brief
`base64`	Standard base64, for protocol and glTF bytes.
`deflate`	DEFLATE (RFC 1951) and zlib (RFC 1950) encoding: matches found in a 32 KiB window through chains of three-byte hashes, one step of lazy matching, and each block’s own Huffman codes, their lengths held to the format’s limits by package-merge. A stream that would come out longer than the bytes themselves is stored instead.
`directory`	A directory’s files as one `Rows<Int>`, and the operations a scene asks on them, as one too: what `input x: Rows<Int> = files "dir/";` holds and what `output y <- z to files "dir/";` carries.
`file`	A Field as a file: a text header naming shape, extent and layout, then the elements as kept, little-endian: a word per scalar, fewer bytes where the layout keeps a scalar narrow (`f:unorm8`).
`font`	A font’s Fields, as `entelechy import` writes them from a font file and `entelechy export` writes a font file from them: the layouts both sides read. A glyph’s outline is line segments in ems, y up, each contour closed and its segments one after another, filled by the nonzero rule.
`ies`	A light’s photometry in IES LM-63 (`.ies`) as rows of candela: one a degree from the light’s aim (0, type C’s nadir) to straight behind it (180), each the mean over the file’s horizontal planes, linearly between the file’s vertical angles and none past them. The candela multiplier and the ballast factor are taken in; a tilt is not.
`inflate`	DEFLATE (RFC 1951) and zlib (RFC 1950) decoding, bit by bit through canonical Huffman tables; `deflate` encodes.
`midi`	A standard MIDI file as rows of notes: start, duration, key, velocity, channel. Ticks and the tempo map become seconds here, so a Kernel plays a score against `time()`. Encoding writes one track of strikes and releases at the caller’s tempo.
`png`	PNG as Fields: decodes to a pixel grid or a `Grid<Float>` of samples (bit depths 1 to 16, every color type, palettes; interlaced files are refused); encodes a pixel grid.
`ppm`	Binary PPM (P6) import and export for Host images.
`rig`	The row layouts of a mesh and its rig (RIGS), shared by import and export, and their matrix product.
`table`	Data tables: CSV and JSON read as rows of the element a Kernel reads them as, and rows written as them. The caller gives the name of each number an element holds (`pos.x`, `items.0`, `look.race`; one number alone is unnamed) and the element’s layout; a record gives each named number its value.
`wav`	WAV as rows: decodes to `Rows<Float>` (mono) or `Rows<Vec2>` (stereo), samples in `-1..=1`; encodes as 16-bit PCM. The sample rate belongs to the file and is returned beside the Field.

Structs

Name	Brief
`ies::Profile`	A light’s photometry, as a profile.
`midi::Note`	One note, as a scene reads it: `struct Note { start: Float; duration: Float; pitch: Int; velocity: Float; channel: Int; }`
`midi::Song`	The notes a file holds, and what was left out of it.
`png::Decoded`	A decoded PNG: samples in `0..=1`, `channels` per pixel (1 gray, 2 gray+alpha, 3 RGB, 4 RGBA).
`table::Element`	The element a table’s rows are read as: the name of each number it holds, in layout order, and the layout.
`wav::Decoded`	A decoded sound: frames of one or two channels, and the file’s rate.

Enumerations

Name	Brief
`directory::Op`	One operation on a directory’s files.
`file::FileError`	Why bytes are not a Field file.
`font::Part`	Which of a font’s Fields a layout is.
`inflate::InflateError`	Why bytes are not a zlib stream.
`png::PngError`	Why bytes are not a PNG the Host can take.
`ppm::PpmError`	Why a PPM file could not be read.
`rig::Part`	One part of a mesh or of its rig, as a file of rows.
`wav::WavError`	Why bytes are not a WAV the Host can take.
`EncodeError`	Why a Field was not encoded.

Functions

Function	Brief
`fn unbase64(text: &str) -> Result<Vec<u8>, String>`	Decodes standard base64, with or without padding; padding and white space anywhere are passed over.
`fn base64(bytes: &[u8]) -> String`	Standard base64 with padding.
`fn deflate(bytes: &[u8]) -> Vec<u8>`	Bytes as a DEFLATE stream of compressed blocks.
`fn zlib(bytes: &[u8]) -> Vec<u8>`	Bytes as a zlib stream: compressed, or stored where that is shorter.
`fn checked_path(path: &str) -> Result<(), String>`	Whether `path` names a file under a directory as the operations and the files’ listing spell it; why not.
`fn pack(files: &[(String, Vec<u8>)]) -> Result<FieldData, String>`	The files, each its path and bytes, packed in the order given.
`fn pack_listing(files: &[(String, u64)]) -> Result<FieldData, String>`	The files listed, each its path and size in bytes, in the order given: `[n, (path_len, size, path..)*]`.
`fn ops(data: &FieldData) -> Result<Vec<Op>, String>`	The operations a Field holds, in order; refused whole when any is malformed, so none of them is done.
`fn encode(schema: &Schema, domain: Domain, storage: &[u32]) -> Vec<u8>`	Encodes a Field with its layout and extent, from its storage.
`fn encode_data(data: &FieldData) -> Vec<u8>`	Encodes Field data.
`fn words(start: &[u8]) -> Result<usize, FileError>`	The words a Field file’s elements take, from its first bytes: what a reader checks against its room before it reads the rest.
`fn header_whole(start: &[u8]) -> bool`	Whether `start`, a Field file’s first bytes, holds its header whole.
`fn layout(start: &[u8]) -> Result<(Schema, Domain, usize), FileError>`	A Field file’s layout and extent, and the byte its elements start at, from its first bytes (its whole header, `header_whole`).
`fn from_words(schema: Schema, domain: Domain, words: Vec<u32>, bytes: usize) -> Result<FieldData, FileError>`	A Field file’s Field from its elements read as little-endian words (`layout` says from where), the last padded with zeros, and how many bytes they were.
`fn decode(bytes: &[u8]) -> Result<FieldData, FileError>`	Decodes a Field file.
`fn glyph_schema() -> Schema`	A glyph’s row, as a Kernel declares it to read one: `code: Int; advance: Int; first: Int; count: Int; lo: Vec2; hi: Vec2`. The advance is in the font’s units, so a line’s advances sum exactly; the box is in ems. A code of -1 is the font’s glyph for a character it lacks.
`fn segment_schema() -> Schema`	A segment of an outline, `a.x, a.y, b.x, b.y` in ems: `Rows<Vec4>`.
`fn metrics_schema() -> Schema`	The font’s measures: `units: Int; ascent: Float; descent: Float; gap: Float`, the font’s units in an em and the rest in ems.
`fn read(bytes: &[u8]) -> Result<Profile, String>`	Reads an LM-63 file of type C photometry (every light fixture’s but floodlights’ and road lights’).
`fn field(profile: &Profile) -> Result<FieldData, String>`	A profile as rows of one float, candela a degree.
`fn inflate(bytes: &[u8], most: usize) -> Result<Vec<u8>, InflateError>`	Decodes a raw DEFLATE stream of at most `most` bytes; a longer one is an error before it is held.
`fn adler32(bytes: &[u8]) -> u32`	Adler-32 of `bytes`.
`fn unzlib(bytes: &[u8], most: usize) -> Result<Vec<u8>, InflateError>`	Decodes a zlib stream of at most `most` bytes and checks its trailer.
`fn schema() -> Schema`	The Field a score is written as: five words a note.
`fn words(note: &Note) -> [u32; 5]`	The words of a note, in the schema’s order.
`fn note(words: &[u32]) -> Note`	A note read back from its words.
`fn field(song: &Song) -> Result<FieldData, String>`	A song’s notes as rows of `schema`; a song needs at least one note.
`fn encode(notes: &[Note], beats: f32) -> Vec<u8>`	A MIDI file of these notes at `beats` quarter notes a minute: one track, the tempo, then strikes and releases in time order.
`fn read(bytes: &[u8]) -> Result<Song, String>`	Reads a standard MIDI file, notes in seconds by the tempo map.
`fn crc32(bytes: &[u8]) -> u32`	CRC-32 as PNG uses it.
`fn decode(bytes: &[u8]) -> Result<Decoded, PngError>`	Decodes a PNG to samples.
`fn decode_within(bytes: &[u8], most: usize) -> Result<Decoded, PngError>`	`decode`, refusing a picture of more than `most` pixels before its data is inflated.
`fn decode_field(bytes: &[u8], gray: bool, words: usize) -> Result<FieldData, PngError>`	Decodes a PNG as a grid of pixels (`gray` false) or a `Grid<Float>` of its luminance or gray samples (`gray` true), of at most `words` words.
`fn encode(width: u32, height: u32, pixels: &[[f32; 4]]) -> Vec<u8>`	Encodes RGBA pixels (`0..=1`) as a compressed PNG of 8-bit samples. An image of at most 256 colors is written as their palette and an index a pixel, packed into as few bits as hold the palette, rows unfiltered; any other as RGBA, each row filtered as whichever of PNG’s filters leaves it the smallest bytes (their sum as signed values). Either decodes to the same pixels.
`fn read(path: &Path) -> Result<Image, PpmError>`	Reads a P6 file into an `Image`.
`fn decode(bytes: &[u8]) -> Result<Image, PpmError>`	Decodes P6 bytes.
`fn decode_field(bytes: &[u8]) -> Result<FieldData, PpmError>`	Decodes P6 bytes as a pixel grid or P5 bytes as a `Grid<Float>` of samples in `0..=1`.
`fn encode_gray(width: u32, height: u32, samples: &[f32]) -> Vec<u8>`	Encodes a `Grid<Float>` as P5 bytes, clamping samples to `0..=1`.
`fn encode(image: &Image) -> Vec<u8>`	Encodes an image as P6 bytes, clamping components to `0..=1`.
`fn multiply(a: &Matrix, b: &Matrix) -> Matrix`	The product `a · b`.
`fn is_table(extension: &str) -> bool`	Whether `extension` names a data table.
`fn row_names(bytes: &[u8], extension: &str) -> Result<Vec<String>, String>`	The names of a table’s rows, its `#name` cells in order (empty where a row has none): what another table’s `table:name` cells count by.
`fn decode(bytes: &[u8], extension: &str, element: &Element<'_>, words: usize, tables: &dyn Fn(&str) -> Result<Vec<String>, String>) -> Result<FieldData, String>`	A table’s rows as a `Rows` Field of `element`, from the file’s bytes; `extension` says which format. A table that would hold more than `words` words is refused before it is laid out. `tables` gives the row names of the table a `table:name` cell names.
`fn encode(data: &FieldData, names: &[String], extension: &str) -> Result<Vec<u8>, String>`	A `Rows` Field as the table `extension` names, each number under `names` (the element’s, as `Element` holds them): what `decode` reads back word for word. A CSV’s heading line names the columns, one number alone `value`; a JSON array holds a row an object, the dots nesting objects and the numbered parts arrays, one number alone a number. An `[Int; N]` whose every row holds text (characters, then zeros) is written as that text under the array’s name. A JSON table cannot hold a NaN or an infinity.
`fn decode(bytes: &[u8]) -> Result<Decoded, WavError>`	Decodes a RIFF WAVE file of PCM (8, 16, 24, or 32-bit) or 32-bit float samples; more than two channels keep the first two.
`fn encode(words: &[u32], channels: usize, rate: u32) -> Vec<u8>`	Encodes rows of `channels` floats (1 or 2) as 16-bit PCM at `rate`.
`fn byte(sample: f32) -> u8`	A picture’s sample (`0..=1`, clamped) as the byte every 8-bit form of it holds: what a PNG or PPM writes and the pointer a scene draws shows.
`fn writable(path: &Path) -> Result<(), String>`	Whether `encode` writes a file of `path`’s extension; the error says which extensions it writes.
`fn extension(path: &Path) -> String`	A file’s extension, lowercased; empty when it has none.
`fn read_bytes(path: &Path) -> Result<(FieldData, String), String>`	Reads a file as `Rows<Int>`, one byte (0 to 255) an element, for a Kernel to parse.
`fn decode_bytes(bytes: &[u8]) -> Result<(FieldData, String), String>`	Bytes already read, as `read_bytes` takes a file’s.
`fn read(path: &Path, want: Option<&str>) -> Result<(FieldData, String), String>`	Reads a file: `.field` as the Host writes it; `.png`, `.ppm`, `.pgm` as a pixel grid, or a `Grid<Float>` of luminance when `want` says so; `.wav` as rows of one or two floats; `.mid` as rows of `midi::Note`; `.ies` as rows of candela a degree (`ies`). Returns the Field and a line describing it.
`fn header_whole(start: &[u8], path: &Path) -> bool`	Whether `start`, a file’s first bytes, holds all its header says of the Field it decodes to: always, but for a Field file whose header runs past them.
`fn fits(start: &[u8], path: &Path, words: usize) -> Result<(), String>`	Whether the Field in a file `start` begins holds `words` words at most, where its first bytes say (a `.field`’s whole header, `header_whole`); a reader asks before it reads the rest.
`fn describe(data: &FieldData) -> String`	The line a Field read from a file is described by: its shape, its count and its layout.
`fn decode(bytes: &[u8], path: &Path, want: Option<&str>, words: usize) -> Result<(FieldData, String), String>`	`read` on bytes already read; `path`’s extension names the format. A compressed picture that would hold more than `words` words is refused before it is inflated.
`fn encode_bytes(data: &FieldData) -> Result<Vec<u8>, String>`	A `Rows<Int>` of bytes (0 to 255) as those bytes: the inverse of `read_bytes`.
`fn encode(data: &FieldData, extension: &str, rate: Option<u32>, names: Option<&[String]>) -> Result<Vec<u8>, EncodeError>`	A Field as the file `extension` names. `rate` is a WAV’s frames a second or a MIDI file’s quarter notes a minute; `names` the name of each number of an element, as a data table’s columns name them, which only a table needs.

Constants

Name	Type	Value	Brief
`directory::WRITE`	`i32`	`0`	The operation writing a file, by its number.
`directory::REMOVE`	`i32`	`1`	The operation removing a file.
`directory::RENAME`	`i32`	`2`	The operation renaming a file.
`file::HEADER_BYTES`	`usize`	`256`	The bytes first read for a Field file’s header; a header longer than these (a wide layout’s) is read further (`header_whole`).
`ies::ROWS`	`usize`	`181`	The rows a profile holds: one a degree, 0 to 180.
`midi::DIVISION`	`u16`	`480`	Ticks to the quarter note in a written file.
`DEFAULT_RATE`	`u32`	`48_000`	The frames a second a WAV is written at by default.
`DEFAULT_BEATS`	`f32`	`120.0`	The quarter notes a minute a MIDI file is written at by default.
`WRITTEN`	`[&str; 9]`	`_`	The extensions `encode` writes.

Type aliases

Name	Type	Brief
`rig::Matrix`	`[f32; 16]`	A 4×4 matrix, column by column, as glTF and the ABI keep one.

ies::Profile

crates/interface/formats/src/ies.rs#L14

A light’s photometry, as a profile.

Properties

Name	Type	Description
`candela`	`Vec<f32>`	Candela a degree from the aim, `ROWS` of them.
`peak`	`f32`	The most of them.
`planes`	`usize`	The horizontal planes the file held.

Implemented traits: Clone, Debug, PartialEq, StructuralPartialEq

midi::Note

crates/interface/formats/src/midi.rs#L13

One note, as a scene reads it: struct Note { start: Float; duration: Float; pitch: Int; velocity: Float; channel: Int; }

Properties

Name	Type	Description
`start`	`f32`	Seconds from the start of the song.
`duration`	`f32`	Seconds it sounds for.
`pitch`	`i32`	The key, 0 to 127; 60 is middle C.
`velocity`	`f32`	How hard it was struck, 0 to 1.
`channel`	`i32`	The channel it played on, 0 to 15; 9 is the drum channel.

Implemented traits: Clone, Copy, Debug, PartialEq, StructuralPartialEq

midi::Song

crates/interface/formats/src/midi.rs#L130

The notes a file holds, and what was left out of it.

Properties

Name	Type	Description
`notes`	`Vec<Note>`	The notes, by when they start.
`tracks`	`usize`	How many tracks the file held.
`left_out`	`Vec<String>`	What was left out.

Implemented traits: Clone, Debug, PartialEq, StructuralPartialEq

png::Decoded

crates/interface/formats/src/png.rs#L37

A decoded PNG: samples in 0..=1, channels per pixel (1 gray, 2 gray+alpha, 3 RGB, 4 RGBA).

Properties

Name	Type	Description
`width`	`u32`	Width in pixels.
`height`	`u32`	Height in pixels.
`channels`	`usize`	Samples per pixel.
`samples`	`Vec<f32>`	Samples row by row.

table::Element

crates/interface/formats/src/table.rs#L35

The element a table’s rows are read as: the name of each number it holds, in layout order, and the layout.

Properties

Name	Type	Description
`names`	`&'a [String]`	A name for each number, as `entelechy_ir`’s `number_names` gives them.
`schema`	`&'a Schema`	The layout the numbers are kept in.

wav::Decoded

crates/interface/formats/src/wav.rs#L30

A decoded sound: frames of one or two channels, and the file’s rate.

Properties

Name	Type	Description
`field`	`FieldData`	The Field: `Rows` of one float per frame or two.
`rate`	`u32`	The file’s frames per second.
`channels`	`usize`	Channels kept: 1 or 2.

directory::Op

crates/interface/formats/src/directory.rs#L25

One operation on a directory’s files.

Variants

Name	Description
`Write { path: String, bytes: Vec<u8> }`	The file `path` holds `bytes`, made when absent.
`Remove { path: String }`	The file `path` is removed.
`Rename { from: String, to: String }`	The file `from` is renamed `to`.

Methods

Function	Description
`fn path(&self) -> &str`	The path the operation acts on first.

Implemented traits: Clone, Debug, Eq, PartialEq, StructuralPartialEq

file::FileError

crates/interface/formats/src/file.rs#L17

Why bytes are not a Field file.

Variants

Name	Description
`Header(String)`	The header is missing or malformed.
`Length { expected: usize, found: usize }`	The body length differs from the header’s count.
`Host(HostError)`	The Host refused the Field.

Implemented traits: Debug, Display, Error

font::Part

crates/interface/formats/src/font.rs#L33

Which of a font’s Fields a layout is.

Variants

Name	Description
`Glyphs`	Glyph rows, `glyph_schema`.
`Segments`	Outline segments, `segment_schema`.
`Metrics`	The measures, `metrics_schema`.

Methods

Function	Description
`fn of(schema: &Schema) -> Option<Self>`	The part of a font `schema` lays out, if any.

Implemented traits: Clone, Copy, Debug, Eq, PartialEq, StructuralPartialEq

inflate::InflateError

crates/interface/formats/src/inflate.rs#L8

Why bytes are not a zlib stream.

Variants

Name	Description
`Format(String)`	The stream ended early or is malformed.
`Checksum`	The Adler-32 trailer does not match the output.

Implemented traits: Debug, Display, Error

png::PngError

crates/interface/formats/src/png.rs#L14

Why bytes are not a PNG the Host can take.

Variants

Name	Description
`Format(String)`	The file is malformed or uses an unsupported feature.
`Inflate(InflateError)`	The compressed data is broken.
`Host(HostError)`	The Host refused the Field.

Implemented traits: Debug, Display, Error

ppm::PpmError

crates/interface/formats/src/ppm.rs#L10

Why a PPM file could not be read.

Variants

Name	Description
`Io(Error)`	The file could not be read.
`Format(String)`	The file is not a binary PPM with 8-bit samples.
`Host(HostError)`	The Host rejected the image.

Implemented traits: Debug, Display, Error, From

rig::Part

crates/interface/formats/src/rig.rs#L9

One part of a mesh or of its rig, as a file of rows.

Variants

Name	Description
`Vertices`	A vertex at rest: position, normal, uv (`f×8`).
`TangentVertices`	A vertex at rest with the tangent a normal map is read along: position, normal, uv, tangent (`f×12`; the tangent’s `w` the handedness, the bitangent `cross(normal, tangent) * w`).
`Triangles`	Three vertex indices (`i×3`).
`Weights`	A vertex’s four joints, then their weights (`i×4, f×4`).
`Skeleton`	A joint’s parent, then its inverse bind matrix (`i, f×16`).
`Clip`	A joint’s local translation, rotation and scale in one frame (`f×10`).

Methods

Function	Description
`fn schema(self) -> Schema`	The layout of one row.
`fn of(schema: &Schema) -> Option<Part>`	The part `schema`’s rows are, matched by scalars and ignoring storage encodings (`u16` triangles, `u8` joints).

Implemented traits: Clone, Copy, Debug, Eq, PartialEq, StructuralPartialEq

wav::WavError

crates/interface/formats/src/wav.rs#L11

Why bytes are not a WAV the Host can take.

Variants

Name	Description
`Format(String)`	The file is malformed or uses an unsupported format.
`Host(HostError)`	The Host refused the Field.

Implemented traits: Debug, Display, Error

EncodeError

crates/interface/formats/src/lib.rs#L325

Why a Field was not encoded.

Variants

Name	Description
`Unknown`	The extension names no format here.
`Unfit(&'static str)`	The Field does not fit the format; the words follow “it is”.
`Unnamed`	A data table was asked for without the names of its columns.
`Table(String)`	The rows do not go into the table; why.

Implemented traits: Clone, Debug, Display, Eq, PartialEq, StructuralPartialEq