DOCSEARCHbyAlgolia
Submit Docs

Inochi2D

repository·main·Indexed 23 days ago

https://github.com/inochi2d/inochi2d

A real-time 2D puppet animation library and reference implementation of the Inochi2D Puppet standard. It enables deforming 2D meshes from layered illustrations to simulate 3D movement. The library is renderer-agnostic, generating Draw Lists for consumption by a renderer, and requires an OpenGL 3.1 context. It is primarily written in D but provides a C FFI for integration with C, C++, and Rust, as well as official bindings for Godot and WebAssembly support.

Tokens
6.6K
Snippets
17
Records
45
Agent score
79%

What's inside Inochi2D

  1. What is Inochi2D?

    main
    Inochi2D is a real-time 2D live2D animation library and the reference implementation of the Inochi2D standard. It works by deforming a 2D mesh bound to layered art assets based on provided parameters at runtime. This deformation allows for 3D-like depth and animation effects within 2D graphics.

  2. Overview of Inochi2D

    main
    Inochi2D is a real-time 2D puppet animation library and serves as the reference implementation for the Inochi2DPuppet standard. It enables the deformation of meshes created from layered illustrations based on parameters at runtime, providing depth and movement to 2D characters.

  3. Understand the INP2 Puppet File Structure

    main

    An Inochi2D Puppet (starting from version 0.9) uses a custom file format. The root of the file is a DataNode object that must contain specific top-level keys to be valid.

    Note: It is highly recommended to read the base serialization format document (inp2.md) before working with this specification, as INP_SECT relies on the INP format rather than JSON.

  4. Understand the INP 2 Format Specification

    main
    INP 2 is a little-endian binary format introduced in Inochi2D 0.9. It is designed to be more robust than the previous INP1 format. The format is 32-bit aligned and consists of tagged data nodes. All INP2 streams must begin with the magic bytes TRNSRTS2 (0x54524E5352545332).

  5. Use `EXT_SECT` for vendor-specific metadata

    main

    The EXT_SECT (optional) allows applications to attach custom metadata to a puppet. This section is an object where:

    • Keys: The Reverse Domain Notation of the source application (e.g., com.example.app).
    • Values: A blob containing the application-specific data.

  6. Parse INP 2 Arrays and Objects

    main

    INP 2 supports recursive complex types:

    Arrays

    • Start with an Array Begin Sentinel tag (0x10). The metadata contains the element count.
    • Followed by the DataNode values of the array elements.
    • Terminated by an Array End Sentinel tag (0x11).

    Objects

    • Start with an Object begin sentinel tag (0x12). The metadata contains the element count.
    • Followed by key-value pairs.
    • Keys use the 0xF0 tag (UTF-8 string).
    • Values use standard DataNode tags.
    • Terminated by an Object end sentinel tag (0x13).
    // Object with 1 element
0x00 0x00 0x01 0x12

// Key with 3 characters: "abc\0"
0x00 0x00 0x03 0xF0 
0x61 0x62 0x63 0x00

// Value: 42 (signed 32-bit integer)
0x00 0x00 0x00 0x02
0x00 0x00 0x00 0x2A

// Object end
0x00 0x00 0x00 0x13

  7. Use DrawCmd variables for node-specific data

    main

    Each DrawCmd includes a vars field, providing up to 64 bytes of variable space per command. This space is used to store additional data required by specific nodes.

    To correctly interpret this data:

    1. Check the type field of the DrawCmd to determine which node type the data pertains to.
    2. Consult the specific documentation for that Node type to understand the layout and meaning of the data stored in vars.

  8. Understand the Inochi2D Draw List system

    main

    Inochi2D is a renderer-agnostic API. Instead of drawing directly to a screen, it generates Draw Lists during a render pass. A Draw List is a buffer containing mesh data, state changes, texture sources, and uniform data.

    To render Inochi2D content, you must implement a renderer that consumes a series of DrawCmd instances.

    Requirements for your renderer:

    • Support for index/element data.
    • Support for vertex offsets (if your API does not support vertex offsets, set useBaseVertex in the Draw List to false).
    struct DrawCmd {
    in_texture_t*[8]    sources;
    in_drawstate_t      state;
    in_blend_mode_t     blendMode;
    in_mask_mode_t      maskMode;
    uint32_t            allocId;
    uint32_t            vtxOffset;
    uint32_t            idxOffset;
    uint32_t            elemCount;
    uint32_t            type;
    void[64]            vars;
}

  9. Available language bindings and implementations

    main

    While the main repository is the reference implementation, there are several ways to use Inochi2D depending on your language and platform needs:

    • D Language: The primary reference implementation.
    • C/C++, Rust, etc.: Use inochi2d-c to interface with the library from languages other than D.
    • Rust: A pure Rust implementation of the Inochi2D specification is being developed in Inox2D.

  10. Handle INP 2 Strings and Blobs

    main

    For both Strings (tag 0x05) and Blobs (tag 0x06), the length handling depends on the size:

    1. If the length is $\le$ 16777214 (0x00FFFFFE) bytes, the length is stored in the tag's metadata.
    2. If the length is $>$ 16777214 bytes, the length is appended as an unsigned integer after the tag.

    Note for Blobs: All blobs must be followed by a CRC-32 checksum using the ISO-3309 polynomial 0xedb88320.

    // Example: Binary blob, length 13.
0x00 0x00 0x0D 0x06

// "Hello, world!\0\0\0"
0x48 0x65 0x6C 0x6C 
0x6F 0x2C 0x20 0x77 
0x6F 0x72 0x6C 0x64 
0x21 0x00 0x00 0x00

// CRC-32
0xEB 0xE6 0xC6 0xE6

  11. Use Inochi2D in C, C++, or Rust

    main

    To use Inochi2D in C, C++, or Rust, build the SDK with the dynamic configuration.

    Important Implementation Detail: When writing your own bindings, Inochi2D uses the cdecl calling convention on all platforms.