Documentation (2.0.3)

Main Menu

File

• New (CRTL+N)

  Creates a new image. Beware of the displayed memory usage per layer. When the number turns yellow or red, the program will use a lot of memory and might crash when using too many layers.

• Open (CRTL+O)

  Opens an image from a file.

• Save (CRTL+S)

  Saves the current image. Prompts the user for a filename if image was not saved previously.

• Save As

  Saves the current image. Always prompts the user for a filename.

• Exit (ALT+F4)

  Exits the program.

View

• Console

  Toggles display of the console.

• Fullscreen (F11)

  Toggles fake fullscreen mode, by resizing the window to take up the entire screen and removing the border.

Presets

• Save All

  Saves all presets with unsaved changes.

Windows

• Manage Charsets

  Openes a window that allows the user to select from all available charsets. Information about how to add new charsets is found with the documentation of the charset file format. Note that the default charset is always available.

• Manage Palettes

  Opens a window that allows the user to select from all available colour palettes.
  The user is also able to add, rename and save colour palettes. Note that unsaved palettes and palettes with unsaved changes are displayed with a * behind their name.

  • Add

    Adds a new colour palette and selects it. The palette is by default filled with the standart 16 colours supported with the Windows VGA palette and Gray otherwise. Note that this default colour palette is always available when starting the program.

  • Rename

    Renames the selected colour palette.

  • Save

    Saves the selected colour palette. For more information read the documentation of the colour palette file format.

Export

• Image to PNG

  Exports the entire image to an png image.

• Selection to PNG

  Exports the selected part of the image to a png image.

• Layer to TXT

  Exports the active layer to an text file.

• Selection to TXT

  Exports the selected part of the active layer to a text file.

Help

• About

  Shows an about window containing credits and the programs version number. It also has a button to check if a newer version of advASCIIdraw is available and features links to related websites and contact information.

• Documentation

  Opens this webpage.

Tools

Tools are selected by clicking their icon in the tool bar to the right, or by using the appropriate shortcut. The status bar at the bottom of the screen shows which tool is selected and some tools use it to show additional useful information about their status.
Most tools also have an additional options bar that appears at the top of the screen when the tool is selected. It features additional functions and settings to modify how the tool works.
While most of the tools functions are accessible with the mouse, there are some features that require the use of the keyboard.

Lastly, there are certain features that are always available regardless of the selected tool:

• Panning

  The user can pan around the image by dragging it with the secondary mouse button.

• Zooming

  The user can zoom in and out of the image by using the mouse wheel.

Charset Window

Note that the charset window functions very similarly to the palette window and their documentation is virtually identical

The charset window lets the user select which character or characters they want to draw. One can either draw a specific character, or use modifyable presets to create customised brushes. Whether single characters or presets are used depends on which tab in the window is active.

Single Tab

• Selection Box

  By pressing and holding the primary mouse button on the selection box, the user can open a pop up showing the entire charset. A different character can be chosen by dragging and releasing the mouse when the desired character is selected.

Preset Tab

The preset tab allows for the creation and use of customisable brushes. A preset consists of any number of characters, each of them associated with a percentage, all of them adding up to 100%. When the preset is used to draw, characters are selected from it at random, according to these percentages.

• Preset Management

  The preset tab features a drop down list box, that holds all available presets. A preset can be selected by clicking the box and selecting the desired preset in the appearing list box.
  Additionally, presets can be added, renamed, saved and deleted. Note that presets that have unsaved changes are marked with a * after their name. The program does not prompt the user to save unsaved presets on exit.

  • Add

    Adds new empty preset to the bottom of the preset list an d selects it.

  • Rename

    Opens a prompt to rename to selected preset. Only alphanumerial characters, spaces, - and _ are allowed.

  • Save

    Saves the selected preset. For the saving directtory and file format check the documentation on the preset file format.

  • Del

    Deletes the currently selected preset. Also deletes the corresponding preset file.

• Preset Manipulation

  The selected preset is displayed in a list box, one character per line. For each character there are individual settings:

  • ASelect Character

    Shows the character selected for this preset item. Pressing with the primary mouse button opens a character selection box, identical to the one used on the single selection tab.

  • -Decrease Percentage

    Decreases the percentage with which this character is drawn. Increases the percentage for all other characters in the preset.

  • +Increase Percentage

    Increases the percentage with which this character is drawn. Decreases the percentage for all other characters in the preset.

  • xRemove Character

    Deletes that character from the preset.

  • +++Add New Character

    Adds a new character to the preset. The default character is the erasing one, and the default percentage is 0%, unless this is the first character, where it is 100%

Palette Window

Note that the palette window functions very similarly to the charset window and their documentation is virtually identical

The palette window lets the user select which colour or colours they want to draw. One can either draw a specific colour, or use modifyable presets to create customised brushes. Whether single colours or presets are used depends on which tab in the window is active.

Single Tab

• Selection Box

  By pressing and holding the primary mouse button on the selection box, the user can open a pop up showing the entire colour palette. A different colour can be chosen by dragging and releasing the mouse when the desired colour is selected.

• • Set

    Opens a colour selection dialog allowing the user to change the selected colour of the preset. Note that these changes are not saved unless the palette is saved in the "Manage Palettes" window, accessible through the main menu.

Preset Tab

The preset tab allows for the creation and use of customisable brushes. A preset consists of any number of colours, each of them associated with a percentage, all of them adding up to 100%. When the preset is used to draw, colours are selected from it at random, according to these percentages.

• Preset Management

  The preset tab features a drop down list box, that holds all available presets. A preset can be selected by clicking the box and selecting the desired preset in the appearing list box.
  Additionally, presets can be added, renamed, saved and deleted. Note that presets that have unsaved changes are marked with a * after their name. The program does not prompt the user to save unsaved presets on exit.

  • Add

    Adds new empty preset to the bottom of the preset list an d selects it.

  • Rename

    Opens a prompt to rename to selected preset. Only alphanumerial characters, spaces, - and _ are allowed.

  • Save

    Saves the selected preset. For the saving directtory and file format check the documentation on the preset file format.

  • Del

    Deletes the currently selected preset. Also deletes the corresponding preset file.

• Preset Manipulation

  The selected preset is displayed in a list box, one colour entry per line. For each entry there are individual settings:

  • ■Select Colour

    Shows the colour selected for this preset item. Pressing with the primary mouse button opens a colour selection box, identical to the one used on the single selection tab.

  • -Decrease Percentage

    Decreases the percentage with which this colour is drawn. Increases the percentage for all other colours in the preset.

  • +Increase Percentage

    Increases the percentage with which this colour is drawn. Decreases the percentage for all other colours in the preset.

  • xRemove Colour

    Deletes that colour from the preset.

  • +++Add New Colour

    Adds a new colour to the preset. The default colour is the first one(index 0), and the default percentage is 0%, unless this is the first colour, where it is 100%

Layer Window

The layer window holds an overview over all the layers in an image, and lets the user select, create, delete and merge layers, hide or show layers, and change a layer's name and other settings.

Layers can be selected by clicking on them, and reorded by dragging them up or down the list with the primary mouse button. Note, that for the purpose of this documentation, the selected layer and the active layer are synonymous.

Layer Management

• New (ALT+N)

  Creates a new layer above the currently active layer and selects the new layer. When no image is open clicking this button opens the new image dialog.

• Delete

  Deletes the selected layer from the image. The layer that was below the selected layer becomes the new selected layer.

• Merge Down

  Merges the selected layer with the layer directly beneath it. The selected layer overrides the second one in all characters that are not set to the erasing/transparent character.

• Overlay Layer

  This displays and toggles whether the active layer is an overlay or transparent layer. Overlay layers are not only transparent on characters set to the erasing/transparent character, but also on the background of all other characters. Aside from artistic purposes, practical applications for this feature include a layer used for semi transparent dust, steam, clouds, smoke and similar effects.

• Background Layer

  This displays and toggles whether the active layer is a background layer. All characters in all background layers are always displayed, even if they are occluded by characters in non-overlay or even other background layers. Aside from artistic purposes, this is useful for changing the background colour or texture of parts of the image.

Layer Options

• Show Layer

  Toggles whether that layer is currently visible. Invisible layers are completely ignored when drawing the image.

• ..Rename Layer

  Temporarily turns the layer name into a text input box allowing the user to change the layer's name.

Keyboard Shortcuts

While shortcuts corresponsing to specific tool or interface options are mentioned above with the corresponding feature, here is a complete list of all keyboard shortcuts and controls in advASCIIdraw:

Interface

Files

• CTRL+N

  Creates a new image.

• CTRL+O

  Opens an image file.

• CTRL+S

  Saves the current image.

Copy & Paste

• CTRL+C

  Copies the currently selected area of the active layer into the system wide clipboard.

• CTRL+X

  Cuts(copies and removes) the currently selected area of the active layer into the clipboard.

• CTRL+V

  Pastes the copied or cut area from the clipboard into the active layer, aligning the top-left most characters of the selection and the pasted area.

Other

• ALT+N

  Creates a new layer.

• ALT+F4

  Exits the application.

• F11

  Toggles borderless window fullscreen mode.

Tools

Select Tools

These keys select their respective tool. Note that you cannot select a different tool with these while the typing tool is selected.

• V

  Select View tool.

• S

  Select Selection tool.

• B

  Select Brush tool.

• T

  Select Typing tool.

Tool Modifiers

These keys change the function of the primary mouse button when using tools.

• ALT

  Selection Tool: Move selection leaving characters in place.

• SHIFT

  Selection Tool: Move selection and selected characters(cuts).

• CTRL

  Selection Tool: Move selection and selected characters, leaving original characters in place(copies).
  Brush Tool: Pipette mode, selecting character and/or colour under cursor for further drawing.

Other Tool Shortcuts

• ←,↑,→,↓

  Type Tool: Move cursor.

• F/INS

  Selection Tool: Fills the selected area with the currently active brush.
  Type Tool (INS only): Inserts character from active brush at cursor.

• X/DEL

  Selection Tool: Clears the selected area. Has the same effect as filling with the erasing character.
  Type Tool (DEL only): Clears character at cursor.

Console

The console of advASCIIdraw has two main functions. First, it confirms certain user actions that do not necessarily have visible effects, like copying into the clipboard. The second function are commands that the user can enter to force certain actions or modify the behaviour of the program in certain ways. Note that when the console displays any status message, entered command or anything else the last line will be shown towards the bottom of the editing area for a few seconds. This is especially useful to confirm that using a shortcut had the desired effect.

The console commands of advASCIIdraw are a feature that most users do not need to worry about. It features mainly commands that are not reachable using the normal user interface and serves purposes of debugging and error reporting. The console can be opened from the View item in the main menu.
A command can be entered into the input field of the console and confirmed by pressing ENTER or with the submit button. Previous commands can be selected, changed and resubmitted by the UP and DOWN arrow keys.

Note that console commands are meant for the experienced user only and have few saveguards to prevent them from causing harm to the running program. The available commands are as follows.

• ? / help

  Lists the available console commands. Add any command as parameter, or type "command?" to display a detailed description for any command.

• c.clear

  Clears the console window.

• c.tofile.all

  Outputs the entire console to a file, and continues writing to it, if no continuous logging is running already.

• c.tofile.start

  Starts logging all future console lines to a file.

• c.tofile.stop

  Stops logging to file.

• charset.set

  Selects the charset with the given name.

• exit / quit

  Exits the application.

• export.png.all

  Exports the entire image to a png file.

• export.png.maxpixels

  Sets or outputs the maximum number of pixels allowed per png export. Set to 0 for no limit. Be aware that exporting very large images can crash the program. The default limit is 16777216pxl or 16Mpxl.

• export.png.selection

  Exports the selected part of the image to a png file.

• export.txt.eol

  Sets or outputs the line ending style with which text files are exported. Allowed values are 'win' and 'unix'.

• export.txt.layer

  Exports the active layer to a text file.

• export.txt.selection

  Exports the selected part of the active layer to a text file.

• image.new

  Creates a new image of given dimensions.

• io.compressfiles

  Toggles whether saved files use compression.

• palette.color.set

  Sets or outputs the hexadecimal value of the colour of specified index of the selected colour palette.

• palette.set

  Selects the palette with the given name.

• rt.offset

  Changes the offset used to draw to render targets. This is used for rendering some listboxes. Changing these values can fix display bugs that happen on some machines. Note that x and y values can be accessed individually by adding ".x" or ".y" to the command.

• selection.drawtransparency

  Toggles whether the erase character in dragged selected areas is drawn as transparent or as red X.

• ui.expandableselectors.fixed

  Toggles whether the character and colour selection pop ups move with relation to the selection or stay fixed while the selection moves.

• version.check

  Connects to amulware.net to check if a newer version of advASCIIdraw is available.

File Formats

Most files used by advASCIIdraw are plain text files and can be edited with any regular text editor. All these plain text files allow for comments marked by the # symbol. Anything in a line after a # is ignored for any of these files. Further, whitespace at the beginning and end of lines as well as empty lines or lines containing only whitespace are also ignored. For all files that represent an entity in the application (like a preset or colour palette) the filename without the extension is also used as a name when displaying that entity.

Unless otherwise specified, all paths below are to be taken with respect to the advASCIIdraw executable.

Settings (.ini)

The advASCIIdraw settings file is located at data/settings.ini. Any line in it will be executed in the applications console upon start of the program. This means that all console commands are valid settings, though not all of them are useful and some of these, like quit may be disallowed in the future.

This file is particularly useful for setting different default settings for the interface or rendering to fix glitches or set user preferred preferences. For changes to the settings file to take effect, the program has to be restarted. The most useful console commands for the settings file are:

• Set custom preferences:

  • charset.set
  • palette.set
  • selection.drawtransparency
  • ui.expandableselecros.fixed
  • export.txt.eol

• Never miss an update:

  • version.check

• Debugging or glitch prevention:

  • c.tofile.all
  • io.compressfiles
  • rt.offset

Presets (.cps)

Saved character and colour preset files can be found in data/gfx/charpresets/ and data/gfx/colorpresets/ respectively. As both charsets and colour palettes have 256 entries, these files are of the same format, though in which folder they are placed changes their meaning.

Each preset can contain any number of lines, each corresponding to an entry in the preset. Each line contains two values seperated by a comma. The first is an integer between 0 and 255 (inclusive), the index of the character or colour. Note that for standard charsets, the character index is equal to the ASCII/ASNI value of that character. The second value, an integer or floating point number, is the freqency of that entry in the preset. These frequencies do not have to be fractions and do not have to sum up to 1, 100 or any other particular number. The program will automatically adjust the preset so that the total percentage of all items will sum to 100%.

Presets are allowed to contain multiple entries with the same index, however there is no intrinsic reason for this being a useful feature.

Charsets (.chr)

Charsets are defined by two files, which should both be placed in data/gfx/charsets/. One of them is an image file that contains the actual symbols in an equally spaced 16x16 grid, counted row first, starting from the top-left corner of the image. Note here that a standard charset should have the appearance of a character coincide with the appropriate ASCII/ANSI character of the same index. However, non-text based charsets are entirely possible.

Note that the allowed image formats are .bmp, .jpg and .png, the last being preferred for its lossless compression and for providing an alpha channel. In fact, if no alpha channel is provided in the image, the lightness will determine the image's transparency, with lighter pixels being more opaque and darker pixels being more transparent. Also note that the image file should be square and have dimensions that are powers of two(128x128, 256x256, ..). Otherwise there might be display errors.

The second file is a plain text file with extension .chr that contains three lines of assignments of the form "attribute = parameter". The three attributes are image, charwidth and charheight. The first takes the filename of the charsets image as parameter, while the other two define the size of a single character in the image, in pixels.

The name used for charsets in the application is the name of the .chr file.

Colour Palette (.pal)

Colour palette files are placed in data/gfx/palettes/ and contain a set of colours used for drawing in ascASCIIdraw.

A palette file can contain up to 256 lines, that each specify one colour of the palette and do so in the order given. Any more than 256 non-empty, non-comment lines will be ignored and if less than 256 colours are specified, the rest will default to Gray (808080). Each line contains its 24bit RGB colour value as a hexadecimal string. For example FFA500 for Orange, or 0000FF for Blue. The three character shorthands, like C40 instead of CC4400, common in web development, are not supported and will be interpreted as 000C40 instead.

ASCII Image Format (.ascii)

The binary .ascii file format used by advASCIIdraw is custom made for the purpose of storing ASCII image information. It is highly flexible with regards to extension in the future and both backwards and forwards compatible.

A detailed description of the format may be added in the future.