convert-characters

Convert images to charset and screens.

Synopsis

convert-characters [-M file] [-o file] [-I directory] [-s section] [-v] specs

Description

Convert images to charsets and screens according to specification file specs, which lists the images to convert and how to convert them.

Images are divided into fixed sized blocks. Distinct blocks are stored in the charset and a screen matrix listing the block indices is created.

It generates an assembler source file containing all the created objects.

Supported Options

-h, --help: Show help message and exit.
-I directory: Search for included files in directory. Can be given multiple times.
-M file: Write gcc-style dependency information to file.
-o file: Write generated assembly code to file.
-s section, --section section: Put generated objects in section section.

Specification File

The specification file uses YAML syntax.

Global Directives

charset: Charset definition or list of charset definition describing the created charsets. (required)
characters: List of character definitions describing images containing characters to convert.
images: List of image definitions describing the images to convert.
section name: Section to place created objects in. (default: data)
screen_width number: Specify the default width of the screen. (default: none)

Charset Directives

This describes the charsets to be created.

align alignment: Align created object to alignment bytes. This is ignored if runlength-encoding is used. (default: no alignment)
count count: Charset contains count characters. (default: 256)
height height: Characters are height logical pixels high. (default: 8)
name string: Specify name of object created for this charset. (required)
predefined: Map of character codes to hex strings. These characters will be defined before processing characters and images. (default: none)
rl-encode boolean: Wether to runlength-encode the charset object (default: false).
section section: Section to place charset object in. (default: global section)
width width: Characters are width logical pixels wide (default: 8).

Character Directives

This describes images containing character sets to include in the created charsets. The contained characters are placed in order, and no screen object will be created.

additional_palette

A map of color values to palette indices which will be added to the palette. (default: none)

charset number

The characters will be stored in charset number (default: 0)

char-size-x number

The width of logical characters in chars. (default: 1)

char-size-y number

The height of logical characters in chars. (default: 1)

file name

The name of the file containing the image.

inverted enum

(default: none)

create: Create inverted characters for this image.
none: No inverted characters are needed for this image.
present: This image contains inverted characters.

offset number

The characters in the image will be placed starting at position number in the created charset. (default: 0)

palette

A map of color values to palette indices. (default: white: 1, black or transparent: 0, 0x40ff40: skip)

pixel-size-x size

Treat size horizontally adjacent pixels (which must be of the same color) as one logical pixel, useful for image formats with non-square pixels. (default: 1)

pixel-size-y size

Treat size vertically adjacent pixels (which must be of the same color) as one logical pixel, useful for image formats with non-square pixels. (default: 1)

Image Directives

This describes an image to encode in the created charsets. A screen object will be created to record the character indices used.

Optionally, the image can be sliced to create multiple screen objects.

additional_palette

A map of color values to palette indices which will be added to the palette. (default: none)

charset

If this is a number, the image will be stored in that charset. If it is a map, the keys are line numbers and the values in which charset to store the portion of the image staring at that line. (default: 0)

file name

The name of the file containing the image.

include-count boolean

For a sliced image, include an object containing the number of screen objects created. (default: true)

include-index boolean

For a sliced image, include an object containing pointers to the screen objects. (default: true)

inverted enum

(default: none)

create: Create inverted characters for this image.
if-different: Store inverted character if it is different from no-inverted one.
none: No inverted characters are needed for this image.
present: This image contains inverted characters.

name string

Name of the created screen or index object. (required)

names string-list

For sliced images, a list of names for the screen object.

palette

A map of color values to palette indices. (default: white: 1, black or transparent: 0, 0x40ff40: skip)

pixel-size-x size

Treat size horizontally adjacent pixels (which must be of the same color) as one logical pixel, useful for image formats with non-square pixels. (default: 1)

pixel-size-y size

Treat size vertically adjacent pixels (which must be of the same color) as one logical pixel, useful for image formats with non-square pixels. (default: 1)

rl-encode boolean

Wether to runlength-encode the screen object. (default: true)

screen-file

screen-width width

The logical width of the screen for this image. If the image is narrower, the remaining bytes will be skipped in the runlength-encoded screen object (default: global screen-width).

slice-x number

Divide the image into number slices horizontally, creating a separate screen object for each slice. (default: 1)

slice-y number

Divide the image into number slices vertically, creating a separate screen object for each slice. (default: 1)

trim enum

Specifies at which end of the encoded screen object skips will be omitted (default: trailing).

none: Don't omit any skips.
both: Omit skips at the beginning and end.
leading: Omit skips at the beginning.
trailing: Omit skips at the end.