[art_types]

This file defines classes for the art objects that are emitted by the Hybrix designer. (The term emitted means that the Hybrix designer automatically generates a code definition for that object.)

• Art resources are objects such as tilemaps, clips, songs, and instruments that are created using the Hybrix designer.
• Unlike board symbols, art objects have a predefined structure that cannot be customized.
• The art members are initialized using data blocks. The data blocks are not shown in the editor because they can be very verbose.
• If an art resource has a name, it can also be accessed using the identifier from the generated file.

# =============================================================================
# ART_TYPES (FRAMEWORK FILE)                                 VERSION 2026-01-25
# =============================================================================
# This file defines classes for art objects that are emitted by the hybrix
# designer.  Unlike symbols, art objects have a predefined structure that
# cannot be customized.

# -----------------------------------------------------------------------------
# An animated bitmap
class clip
  var frames: clip_frame[]
  var width: byte, height: byte
end class

# -----------------------------------------------------------------------------
# One bitmap frame belonging to a clip
class clip_frame
  var pixels: byte[]

  # Measured in video frames
  # 1 = full 30 fps;  2 = 1/2 speed;  3 = 1/3 speed; . . .
  # 0 or 255 = stop animation on this frame
  var duration: byte
end class

# -----------------------------------------------------------------------------
class tile
  # The array index is x*tile_width+y
  var pixels: byte[]
end class

# -----------------------------------------------------------------------------
class tileset
  # The tile index is its index in this array
  var tiles: tile[]
  var jumbo: bool
end class

# -----------------------------------------------------------------------------
class tilemap
  var col_count: pair
  var row_count: pair

  # The array index is: row*col_count+col
  # Each tile code is a 16-bit pair:
  # bits 0..9   encode the tile index (0..1023) from the tileset
  # bits 10..14 encode the theme index (0..31) into io::themes
  # bit  15     if set, io::matte_color replaces any clear pixels in this tile
  var tile_codes: pair[]

  # ---------------------------------------------------------------------------
  func copy_from(source: tilemap)
    source.col_count -> .col_count
    source.row_count -> .row_count

    new pair[](source.tile_codes.size) -> .tile_codes
    .tile_codes.copy_from(source.tile_codes)
  end func
end class

# -----------------------------------------------------------------------------
# A single note played by a track of a song_pattern
class track_event # size 4
  # MIDI note number
  # 0   =  C"-1"     8.176 hz
  # 12  =  C0       16.352 hz
  # 59  =  B3      246.942 hz
  # 60  =  C4      261.626 hz  middle C
  # 69  =  A4      440.000 hz  instrument fundamental frequency
  # 127 =  G9    12543.854 hz
  #
  # 254 = release envelopes
  # 255 = rest
  #
  # C2(36)  D2(38)  E2(40) F2(41)  G2(43)  A2(45)  B2(47)
  # C3(48)  D3(50)  E3(52) F3(53)  G3(55)  A3(57)  B3(59)
  # C4(60)  D4(62)  E4(64) F4(65)  G4(67)  A4(69)  B4(71)
  # C5(72)  D5(74)  E5(76) F5(77)  G5(79)  A5(81)  B5(83)
  var note: byte

  # index into art::instruments[]
  var instrument: byte

  # encoded as u2.6 fixed point (0 .. 3.984375)
  var mod_byte: byte

  # For sounds, samples_per_tick is always 459 samples/tick = 120 bpm.
  # For songs, song_pattern.samples_per_tick defines a tick.
  var duration_ticks: byte
end class

# -----------------------------------------------------------------------------
class track
  # Must have at least one event
  var events: track_event[]
end class

# -----------------------------------------------------------------------------
class song_pattern
  # One track for each sound channel
  var tracks: track[]

  # Classic mod trackers use three timing constants:
  # - beats/min, also called "tempo",  typical is 120 BPM
  # - rows/beat,                       typical is 4 rows per beat
  # - ticks/row, also called "speed",  typical is 6 ticks/row
  # Notes are played by "rows", and "ticks" were used for interpolations only.
  # Our duration is measured in ticks so that it fits in an 8-bit value.
  #
  # 120 BPM = 48 ticks/second = 459 samples/tick
  var samples_per_tick: pair
end class

# -----------------------------------------------------------------------------
class song
  var patterns: song_pattern[]
end class