Add info on animated textures for KH2

OpenKH · Jun 5, 2020 · ce5c27a · ce5c27a
1 parent 823b841
commit ce5c27a
Showing 1 changed file with 98 additions and 0 deletions.
diff --git a/docs/kh2/file/raw-texture.md b/docs/kh2/file/raw-texture.md
@@ -122,3 +122,101 @@ MINx and MAXx are only applied if the [wrap mode](#wrap-mode) is of type `REGION
 | 1     | CLAMP
 | 2     | REGION_REPEAT
 | 3     | REGION_CLAMP
+
+## Texture Animation Metadata
+
+Includes parameters for animating textures. This section appears at the end of the file.
+
+The main header does not directly provide an offset to this metadata. Instead, this offset is calculated as the sum of the CLUT data offset and the total byte size of CLUT data.
+
+Each block begins with a 4-byte tag and an optional byte size field, followed by the data itself.
+
+| Offset | Type    | Descriptor
+|--------|---------|------------
+| 0      | char[4] | Tag name. See below sub-sections for possible tags.
+| 4      | uint32  | Total byte size of data. Present for all tags except _KN5.
+| 8      |         | Data. Varies by tag.
+
+### UVSC (UV Scroll)
+
+Provides a single pair of U and V speed factors for texture scrolling. Entries in the VIF table for the model may apply scrolling by specifying an index corresponding with a UVSC entry.
+
+| Offset | Type    | Descriptor
+|--------|---------|------------
+| 0      | char[4] | "UVSC"
+| 4      | uint32  | Total byte size of data. Always `0xC`.
+| 8      | uint32  | Index of entry.
+| 12     | float   | U scroll speed.
+| 16     | float   | V scroll speed.
+
+### TEXA (Texture Animation)
+
+Provides parameters and image data for rendering sprite animations for a single texture. Consists of one or more frame tables for animations as well as raw image data for individual sprites.
+
+Most of the GS register fields used to upload the base image texture, including the base pointer, buffer width and pixel storage format, are used to upload sprite image data for the active animation frame to GS memory (see [texture info](#texture-info)). The pixel offset and size of the transmission area (dsax, dsay, rrw, rrh) are set such that the upload overwrites the base image at the given region with image data for the sprite. All sprites under a single TEXA tag are the same size and pixel format, which means that these parameters are constant across all animations.
+
+Image data for sprites is stored contiguously. Starting offsets for each image are calculated using a sprite index as well as the sprite dimensions and bits per pixel specified in the tag header.
+
+| Offset | Type    | Descriptor
+|--------|---------|------------
+| 0      | char[4] | "TEXA"
+| 4      | uint32  | Total byte size of data.
+| 8      | uint16  | 
+| 10     | uint16  | Texture index to apply the animation.
+| 12     | uint16  | Frame stride in halfwords for entries in the [frame table](#frame-table-entry).
+| 14     | uint16  | Bits per pixel of sprite image data.
+| 16     | uint16  | Base slot index. Applies to entries in the [slot table](#animation-slot-table).
+| 18     | uint16  | Maximum slot index. Applies to entries in the [slot table](#animation-slot-table).
+| 20     | uint16  | Number of animations.
+| 22     | uint16  | Number of sprites in sprite image data.
+| 24     | uint16  | U offset in base image in pixels (dsax).
+| 26     | uint16  | V offset in base image in pixels (dsay).
+| 28     | uint16  | Sprite width in pixels (rrw).
+| 30     | uint16  | Sprite height in pixels (rrh).
+| 32     | uint32  | Offset of [slot table](#animation-slot-table).
+| 36     | uint32  | Offset of [animation table](#animation-table-entry).
+| 40     | uint32  | Offset of sprite image data.
+| 44     | uint32  | Default animation index (idle).
+
+#### Animation Slot Table
+
+This table contains animation slots where each slot may optionally be assigned an animation index. An external source can enable one of these slots to trigger a certain animation for the texture. The exact interaction with these external files is currently unknown.
+
+| Offset | Type   | Descriptor
+|--------|--------|------------
+| 0      | uint32 | Animation index assigned to the slot (actual index is `value - 1`). If `0`, the slot is empty.
+
+#### Animation Table Entry
+
+| Offset | Type   | Descriptor
+|--------|--------|------------
+| 0      | uint32 | Offset of first frame in the [frame table](#frame-table-entry).
+
+#### Frame Table Entry
+
+| Offset | Type         | Descriptor
+|--------|--------------|------------
+| 0      | uint16 : 0-3 | Frame control. <br> `0`: Enable sprite <br> `1`: Disable sprite (use the base image) <br> `2`: Jump to given frame offset (loop) <br> `3`: Stop the animation
+| 0      | int16 : 4-15 | Loop offset in number of frames. Usually < 0 if present.
+| 2      | uint16       | Minimum length of frame.
+| 4      | uint16       | Maximum length of frame.
+| 6      | uint16       | Sprite image index.
+
+If minimum length < maximum length, a random number between [minimum, maximum] is selected as the length the frame. Random intervals are used in cases such as blinking animations for characters.
+
+### _DMY
+
+Dummy tag used for padding.
+
+| Offset | Type    | Descriptor
+|--------|---------|------------
+| 0      | char[4] | "_DMY"
+| 4      | uint32  | Total byte size of data. Always `0`.
+
+### _KN5
+
+Indicates end of metadata.
+
+| Offset | Type    | Descriptor
+|--------|---------|------------
+| 0      | char[4] | "_KN5"