Image::RGBA::Text format

Image::RGBA::Text allows you to create images with 32 bits per pixel color depth with Red, Green, Blue, and Alpha channels.

An input document can contain one or multiple images. Calling RGBAText.decode with the :all named parameter will return all images as a list, otherwise only the first image will be returned.

Input documents are simply a sequence of lines (determined by what the lines method of the source that is passed to the decode function returns) that are either directives or pixel data.

Directives

=rgba

The =rgba directive starts a new image. The directive itself is followed by two numbers (digits conforming to \d in regex language, and anything that is supported by Perl 6's Int method on Str) and a free text that will be stored in the info attribute of the image object. The two numbers specify the width and height of the image respectively. That is, the first number specifies how many pixels are in each line of the resulting image and the second number specifies how many lines will be expected.

=map

The =map directive sets up "names" for colors that can be used in the pixel data portion of the image. It accepts a list of twos where the first entry is the name that should be available in the pixel data portion and the second entry is a color value as explained in the section Colors.

A map directive only influences pixel data following in the input file, and mappings are reset whenever a =rgba directive is encountered.

Multiple map directives in a row are equivalent to a single map directive containing the first directive's mappings followed by the second map directive's mappings etc.

=scale

The =scale directive is followed by a single number that specifies the default scaling factor that will be used by the image if .scale is called on it with no argument.

Pixel Data

Any line that doesn't start with a = character will be interpreted as pixel data. Every line of pixel data contains one or more space-separated "names" for colors that will be put into the resulting image.

Any entry in the line of pixel data can be any format from the section Colors or anything that was declared with a =map directive. The declared mappings have precedence over the regular formats, so 8 will mean a black transparent pixel unless there is a mapping set up, for example like =map 8 ff0000ff.

The lines don't have to be contain as many entries as the image is wide, but supplying less than a whole line's worth will not fill up the rest of the line in the image with pixels. Instead, all pixel data is interpreted the same way as if they were in one long line: The first N entries will be used for the first line, the next N entries for the second line, and so on.

Lines of pixel data may end in a comment as explained in the section Comments.

Colors

Image::RGBA::Text understands six different ways to specify colors. They are distinguished by the number of characters in each piece.

A single hexadecimal digit

Image::RGBA::Text comes with a default palette for single hexadecimal digits:

#000000FF 0
    #7F0000FF 1
    #007F00FF 2
    #7F7F00FF 3
    #00007FFF 4
    #7F007FFF 5
    #007F7FFF 6
    #7F7F7FFF 7
    #00000000 8
    #FF0000FF 9
    #00FF00FF A
    #FFFF00FF B
    #0000FFFF C
    #FF00FFFF D
    #00FFFFFF E
    #FFFFFFFF F

In words, numbers 0 through 7 are black and dark colors, all opaque. Number 8 is a transparent black pixel. Numbers 9 through F are bright colors followed by white.

Double hexadecimal digits

Double hexadecimal digits, i.e. 00 through FF, will result in a greyscale of opaque pixels. 00 is black, FF is white, the values in between just have the given hexadecimal number for the R, G, B channels and FF for the alpha channel.

Three hexadecimal digits

Three hexadecimal digits will result in opaque pixels where the individual hexadecimal digits are doubled and stored as the R, G, and B value respectively. For example, the value 47e would result in the RGBA color value #4477eeFF.

Four hexadecimal digits

This works the same way as three hexadecimal digits, but the alpha channel takes its value from the fourth digit rather than being fixed at FF.

Six hexadecimal digits

Six hexadecimal digits work exactly like you would expect from HTML, CSS, or graphics software in general: The first two digits are for the red channel, the next two for the green channel, and the last two for the blue channel. The alpha channel is always FF.

Eight hexadecimal digits

This works the same way as six hexadecimal digits, but the last two digits are used for the alpha channel.

Comments

Any line that doesn't start with a = character can have a # sign that indicates the start of a comment. Comments can be followed by any text and will be stored in the image object's comments attribute as a list of pairs with the key being the X and Y position where the comment was started and the value being the text.