Allegro data file: Python parsing library

Allegro library for C (mostly used for game and multimedia apps programming) used its own container file format.

In general, it allows storage of arbitrary binary data blocks bundled together with some simple key-value style metadata ("properties") for every block. Allegro also pre-defines some simple formats for bitmaps, fonts, MIDI music, sound samples and palettes. Allegro library v4.0+ also support LZSS compression.

This spec applies to Allegro data files for library versions 2.2 up to 4.4.

Application

Allegro library (v2.2-v4.4)

KS implementation details

License: CC0-1.0

This page hosts a formal specification of Allegro data file using Kaitai Struct. This specification can be automatically translated into a variety of programming languages to get a parsing library.

Usage

Parse a local file and get structure in memory:

data = AllegroDat.from_file("path/to/local/file.Allegro data file")

Or parse structure from a bytes:

from kaitaistruct import KaitaiStream, BytesIO

raw = b"\x00\x01\x02..."
data = AllegroDat(KaitaiStream(BytesIO(raw)))

After that, one can get various attributes from the structure by invoking getter methods like:

data.packMagic # => get pack magic

Python source code to parse Allegro data file

allegro_dat.py

# This is a generated file! Please edit source .ksy file and use kaitai-struct-compiler to rebuild

from pkg_resources import parse_version
from kaitaistruct import __version__ as ks_version, KaitaiStruct, KaitaiStream, BytesIO
from enum import Enum


if parse_version(ks_version) < parse_version('0.7'):
    raise Exception("Incompatible Kaitai Struct Python API: 0.7 or later is required, but you have %s" % (ks_version))

class AllegroDat(KaitaiStruct):
    """Allegro library for C (mostly used for game and multimedia apps
    programming) used its own container file format.
    
    In general, it allows storage of arbitrary binary data blocks
    bundled together with some simple key-value style metadata
    ("properties") for every block. Allegro also pre-defines some simple
    formats for bitmaps, fonts, MIDI music, sound samples and
    palettes. Allegro library v4.0+ also support LZSS compression.
    
    This spec applies to Allegro data files for library versions 2.2 up
    to 4.4.
    
    .. seealso::
       Source - https://liballeg.org/stabledocs/en/datafile.html
    """

    class PackEnum(Enum):
        unpacked = 1936484398
    def __init__(self, _io, _parent=None, _root=None):
        self._io = _io
        self._parent = _parent
        self._root = _root if _root else self
        self._read()

    def _read(self):
        self.pack_magic = self._root.PackEnum(self._io.read_u4be())
        self.dat_magic = self._io.ensure_fixed_contents(b"\x41\x4C\x4C\x2E")
        self.num_objects = self._io.read_u4be()
        self.objects = [None] * (self.num_objects)
        for i in range(self.num_objects):
            self.objects[i] = self._root.DatObject(self._io, self, self._root)


    class DatFont16(KaitaiStruct):
        """Simple monochrome monospaced font, 95 characters, 8x16 px
        characters.
        """
        def __init__(self, _io, _parent=None, _root=None):
            self._io = _io
            self._parent = _parent
            self._root = _root if _root else self
            self._read()

        def _read(self):
            self.chars = [None] * (95)
            for i in range(95):
                self.chars[i] = self._io.read_bytes(16)



    class DatBitmap(KaitaiStruct):
        def __init__(self, _io, _parent=None, _root=None):
            self._io = _io
            self._parent = _parent
            self._root = _root if _root else self
            self._read()

        def _read(self):
            self.bits_per_pixel = self._io.read_s2be()
            self.width = self._io.read_u2be()
            self.height = self._io.read_u2be()
            self.image = self._io.read_bytes_full()


    class DatFont(KaitaiStruct):
        def __init__(self, _io, _parent=None, _root=None):
            self._io = _io
            self._parent = _parent
            self._root = _root if _root else self
            self._read()

        def _read(self):
            self.font_size = self._io.read_s2be()
            _on = self.font_size
            if _on == 8:
                self.body = self._root.DatFont8(self._io, self, self._root)
            elif _on == 16:
                self.body = self._root.DatFont16(self._io, self, self._root)
            elif _on == 0:
                self.body = self._root.DatFont39(self._io, self, self._root)


    class DatFont8(KaitaiStruct):
        """Simple monochrome monospaced font, 95 characters, 8x8 px
        characters.
        """
        def __init__(self, _io, _parent=None, _root=None):
            self._io = _io
            self._parent = _parent
            self._root = _root if _root else self
            self._read()

        def _read(self):
            self.chars = [None] * (95)
            for i in range(95):
                self.chars[i] = self._io.read_bytes(8)



    class DatObject(KaitaiStruct):
        def __init__(self, _io, _parent=None, _root=None):
            self._io = _io
            self._parent = _parent
            self._root = _root if _root else self
            self._read()

        def _read(self):
            self.properties = []
            i = 0
            while True:
                _ = self._root.Property(self._io, self, self._root)
                self.properties.append(_)
                if not (_.is_valid):
                    break
                i += 1
            self.len_compressed = self._io.read_s4be()
            self.len_uncompressed = self._io.read_s4be()
            _on = self.type
            if _on == u"BMP ":
                self._raw_body = self._io.read_bytes(self.len_compressed)
                io = KaitaiStream(BytesIO(self._raw_body))
                self.body = self._root.DatBitmap(io, self, self._root)
            elif _on == u"RLE ":
                self._raw_body = self._io.read_bytes(self.len_compressed)
                io = KaitaiStream(BytesIO(self._raw_body))
                self.body = self._root.DatRleSprite(io, self, self._root)
            elif _on == u"FONT":
                self._raw_body = self._io.read_bytes(self.len_compressed)
                io = KaitaiStream(BytesIO(self._raw_body))
                self.body = self._root.DatFont(io, self, self._root)
            else:
                self.body = self._io.read_bytes(self.len_compressed)

        @property
        def type(self):
            if hasattr(self, '_m_type'):
                return self._m_type if hasattr(self, '_m_type') else None

            self._m_type = self.properties[-1].magic
            return self._m_type if hasattr(self, '_m_type') else None


    class DatFont39(KaitaiStruct):
        """New bitmap font format introduced since Allegro 3.9: allows
        flexible designation of character ranges, 8-bit colored
        characters, etc.
        """
        def __init__(self, _io, _parent=None, _root=None):
            self._io = _io
            self._parent = _parent
            self._root = _root if _root else self
            self._read()

        def _read(self):
            self.num_ranges = self._io.read_s2be()
            self.ranges = [None] * (self.num_ranges)
            for i in range(self.num_ranges):
                self.ranges[i] = self._root.DatFont39.Range(self._io, self, self._root)


        class Range(KaitaiStruct):
            def __init__(self, _io, _parent=None, _root=None):
                self._io = _io
                self._parent = _parent
                self._root = _root if _root else self
                self._read()

            def _read(self):
                self.mono = self._io.read_u1()
                self.start_char = self._io.read_u4be()
                self.end_char = self._io.read_u4be()
                self.chars = [None] * (((self.end_char - self.start_char) + 1))
                for i in range(((self.end_char - self.start_char) + 1)):
                    self.chars[i] = self._root.DatFont39.FontChar(self._io, self, self._root)



        class FontChar(KaitaiStruct):
            def __init__(self, _io, _parent=None, _root=None):
                self._io = _io
                self._parent = _parent
                self._root = _root if _root else self
                self._read()

            def _read(self):
                self.width = self._io.read_u2be()
                self.height = self._io.read_u2be()
                self.body = self._io.read_bytes((self.width * self.height))



    class Property(KaitaiStruct):
        def __init__(self, _io, _parent=None, _root=None):
            self._io = _io
            self._parent = _parent
            self._root = _root if _root else self
            self._read()

        def _read(self):
            self.magic = (self._io.read_bytes(4)).decode(u"UTF-8")
            if self.is_valid:
                self.type = (self._io.read_bytes(4)).decode(u"UTF-8")

            if self.is_valid:
                self.len_body = self._io.read_u4be()

            if self.is_valid:
                self.body = (self._io.read_bytes(self.len_body)).decode(u"UTF-8")


        @property
        def is_valid(self):
            if hasattr(self, '_m_is_valid'):
                return self._m_is_valid if hasattr(self, '_m_is_valid') else None

            self._m_is_valid = self.magic == u"prop"
            return self._m_is_valid if hasattr(self, '_m_is_valid') else None


    class DatRleSprite(KaitaiStruct):
        def __init__(self, _io, _parent=None, _root=None):
            self._io = _io
            self._parent = _parent
            self._root = _root if _root else self
            self._read()

        def _read(self):
            self.bits_per_pixel = self._io.read_s2be()
            self.width = self._io.read_u2be()
            self.height = self._io.read_u2be()
            self.len_image = self._io.read_u4be()
            self.image = self._io.read_bytes_full()