libkate: Format - header packet type 0x80 - ID header

# Format - header packet type 0x80 - ID header

The ID header must be the first packet in a Kate stream. It carries information about the stream.

Here is a table description of the format of the ID header:

     * Kate bitstream version 0.3
     *
     * Default field type: LITTLE ENDIAN unsigned integer

     0               1               2               3              |
     0                   1                   2                   3  |
     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1| Byte
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    | packtype      | Identifier char[7]: 'kate\0\0\0'              | 0-3
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    | kate magic continued                                          | 4-7
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    | reserved - 0  | version major | version minor | num headers   | 8-11
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    | text encoding | directionality| reserved - 0  | granule shift | 12-15
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    | cw sh |  canvas width         | ch sh | canvas height         | 16-19
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    | reserved - 0                                                  | 20-23
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    | granule rate numerator                                        | 24-27
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    | granule rate denominator                                      | 28-31
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    | language (NUL terminated)                                     | 32-35
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    | language (continued)                                          | 36-39
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    | language (continued)                                          | 40-43
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    | language (continued)                                          | 44-47
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    | category (NUL terminated)                                     | 48-51
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    | category (continued)                                          | 52-55
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    | category (continued)                                          | 56-59
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    | category (continued)                                          | 60-63
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

and for a description of those fields:

- `packtype` the packet type for this header - always 0x80

- `kate` `magic` the 7 byte string "kate\0\0\0", as all other Kate headers

- `version` `major` the major version number of the bitstream

- `version` `minor` the minor version number of the bitstream

- `num` `headers` the number of header packets present in this stream

- `text` `encoding` the default encoding used by text (usually 0, UTF-8)

- `directionality` the default directionality of the text

- `granule` `shift` the number of bits in the granule positions reserved for storing the offset part

- `cw` `sh` (from bitstream 0.2) the number of bits to left shift the `canvas` `width` field to compute the original canvas width
- `canvas` width (from bitstream 0.2) the number to shift left by `cw` `sh` to compute the original canvas width

zero is a valid width, and represents an unset width

- `ch` `sh` (from bitstream 0.2) the number of bits to left shift the `canvas` `height` field to compute the original canvas height
- `canvas` height (from bitstream 0.2) the number to shift left by `ch` `sh` to compute the original canvas height

zero is a valid height, and represents an unset height

- `granule` `rate` `numerator` the numerator of the fraction representing how many granule units represent a second (from bitstream 0.2)

- `granule` `rate` `denominator` the denominator of the fraction representing how many granule units represent a second

- `language` the default language of the text in this stream (will be NUL terminated)

an empty string is a valid language, and represents an unset language

- `category` the category of the text in this stream (will be NUL terminated)

an empty string is a valid category, and represents an unset category

All fields marked as "reserved - 0" should be set to zero when encoding a stream with this version of the bitstream format. However, if decoding a stream encoded with a version of the bitstream format with the same bitstream major version but a higher bitstream minor version, those fields may be non zero, if they were subsequently allocated to carry additional information.