TextUR

Text-based texture UI and Rasterizer.

TextUR is a terminal-based editor for text-based textures or images. This is a tool for generating textures to be used with DungGine. The recommended file extension for texture files is *.tx, though the program doesn't really care about the extension however.

Command Line Arguments

• Command line arguments help : ./textur --help. It lists additional command line arguments.
• Load existing texture : ./textur -f <filename>.
• Create new texture or overwrite existing texture : ./textur -f <filename> -s <num_rows> <num_cols>.
• Trace over another texture : ./textur -f <main_texture_filename> -t <trace_texture_filename>.
• Convert texture made up of bright textels from the textel presets in TextUR to a corresponding dark texture which then can be used for rendering shadows in e.g. DungGine. The program exits when conversion is completed : ./textur -f <source_texture_filename> -c <target_texture_filename>.

Keys

• K : to get a list of all support key presses.
• Escape : close windows.
• WASD (lower case) or arrow keys : navigates the cursor or selects a textel preset in the textel menu. When in the textel menu, left and right (or A and D) scrolls from material to material for quicker navigation among the different textel presets.
• SHIFT + WASD (upper case) keys : scrolls the texture page-wise.
• Space : enter selected textel preset under cursor.
• Z : undo.
• SHIFT + Z : redo.
• C : clear textel under cursor.
• V : toggle drawing of vertical coordinates.
• H : toggle drawing of horizontal coordinates.
• SHIFT + V : toggle drawing of vertical guide line from the horizontal coordinate axis.
• SHIFT + H : toggle drawing of horizontal guide line from the vertical coordinate axis.
• - : toggle hide/show textel presets menu.
• _ : toggle hide/show recently used textels palette. Use up/down or w/s to mark a textel, then Space or Enter to select it.
• X : export (save) work to current file.
• B : brush-stroke. Forms a circle, filled with the currently selected textel preset.
• SHIFT + B : big brush-stroke.
• R : randomized brush-stroke. Same as the B key, but fills the circle with textels according to a normal random distribution. You can re-generate until you get the desired result.
• SHIFT + R : randomized big brush-stroke. Same as the SHIFT + B key, but fills the circle with textels according to a normal random distribution. You can re-generate until you get the desired result.
• F: fill screen. Fills the texture with the currently selected textel preset where the bounding box of the screen is currently located over the texture.
• P : pick a textel from under the cursor and hilite the corresponding preset in the menu.
• L : show location of cursor.
• G : goto new cursor location. Press backspace to clear the last digit, press tab to toggle between R and C coordinate fields and press enter to confirm. Pressing G again toggles the input box.
• T : toggle show/hide of tracing texture.
• I : toggle inverted textels (i.e. toggle between dark and bright textel presets).
• M : toggle show/hide of material id:s.
• SHIFT + E : edit or add custom textel preset.
• E : edit Ad Hoc textel preset (the first in the list). Mat = -1.
• Q : quit.

Custom Textel Presets

Add a file named custom_textel_presets. The file format looks like this:

<textel-preset-name>
'<normal-glyph>', <normal-fg-color>, <normal-bg-color>, <normal-material>
'<shadow-glyph>', <shadow-fg-color>, <shadow-bg-color>, <shadow-material>
<textel-preset-name>
'<normal-glyph>', <normal-fg-color>, <normal-bg-color>, <normal-material>
'<shadow-glyph>', <shadow-fg-color>, <shadow-bg-color>, <shadow-material>
...etc...

<normal-glyph> = <shadow-glyph> := "'" <printable-ascii-char> "'" | "[" <preferred-unicode-codepoint> "|" <printable-ascii-char> "]" where the latter <printable-ascii-char> acts as fallback if the <preferred-unicode-codepoint> can't be rendered.

Comments can be done on separate lines with # in front.

So e.g.

Magic Stone
'%', Magenta, Cyan, 28
'%', DarkMagenta, DarkCyan, 28
# ╮ 7
8-bit + glyph
[256E,7], rgb6:[0, 1, 5], gray24:{19}, 0
[256E,7], rgb6:[0, 3, 4], Transparent2, 0

produces the following textel preset at the end of the list:

Look in TextUR/TextUR/textel_presets for which material number that is appropriate to use for your custom presets.

Screenshots

Older pictures:

Bright mode textels (normal mode):

Dark mode textels (shadow mode):

Dark mode texture (shadow texture):

Recently used textels menu invoked with '_' (SHIFT + '-') keypress.

Unsaved changes indicator:

Confirmation screen for attempting to quit while there are unsaved changes:

Custom textel "Magic Stone":

• Small brush stroke using B key (upper left corner).
• Big brush stroke using SHIFT + B key (lower left corner).
• Small randomized brush stroke using R key (upper right corner).
• Big randomized brush stroke using SHIFT + R key (lower right corner).

Editing Ad Hoc textel preset using E key:

Editing custom textel preset using SHIFT + E key: (see section Custom Textel Presets above for more info)

Keybinds legend invoked by pressing K:

Build & Run Instructions

There are two options on dealing with repo dependencies:

Repo Dependencies Option 1

This method will ensure that you are running the latest stable versions of the dependencies that work with TextUR.

The script fetch-dependencies.py used for this was created by Thibaut Buchert. fetch-dependencies.py is used in the following scripts below:

After a successful build, the scripts will then prompt you with the question if you want to run the program (it will be run with a demo texture).

When the script has been successfully run for the first time, you can then go to sub-folder TextUR and use the build.sh / build.bat script instead.

Windows

Run the following script:

setup_and_build.bat

MacOS / Linux

Run the following script:

setup_and_build.sh

Repo Dependencies Option 2

In this method we basically outline the things done in the setup_and_build-scripts in Option 1.

This method is more suitable for development as we're not necessarily working with "locked" dependencies.

You need the following header-only libraries:

• https://github.com/razterizer/Core
• https://github.com/razterizer/Termin8or

Make sure the folder structure looks like this:

<my_source_code_dir>/lib/Core/                   ; Core repo workspace/checkout goes here.
<my_source_code_dir>/lib/Termin8or/              ; Termin8or repo workspace/checkout goes here.
<my_source_code_dir>TextUR/                      ; TextUR repo workspace/checkout goes here.

These repos are not guaranteed to all the time work with the latest version of TextUR. If you want the more stable aproach then look at Option 1 instead.

Windows

Then just open <my_source_code_dir>/TextUR/TextUR/TextUR.sln and build and run. That's it!

You can also build it by going to <my_source_code_dir>/TextUR/TextUR/ and build with build.bat. Then you run by typing x64\Release\textur followed by the appropriate command line arguments.

MacOS / Linux

Goto <my_source_code_dir>/TextUR/TextUR/ and build with ./build.sh.

Then run by typing ./bin/textur and apply the appropriate command line arguments (see beginning of README.md).

Make New Release

To make a new release, you first have to update the RELEASE_NOTES.md document. E.g.:

Then to make a new release you should use the tag_release.sh script:

./tag_release.sh -f RELEASE_NOTES.md

or if you want to re-upload an existing release, e.g.:

./tag_release.sh 1.1.5.7. -f RELEASE_NOTES.md

you can also use these commands:

./tag_release.sh bump patch "Release notes."

./tag_release.sh bump minor "Release notes."

./tag_release.sh bump major "Release notes."

./tag_release.sh 1.1.5.7 "Release notes."

If you want to remove a release for some reason, you can do so by running the following git commands:

# Delete local tag
git tag -d release-1.0.0.0

# Delete remote tag
git push --delete origin release-1.0.0.0

Running from a Release

When you download a MacOS release then you need to tell the gatekeeper unblock the executable (here: textur), but only if you trust the program of course (check source code + release workflow if you're unsure). When you feel ready, you can allow the binary to be run by going to the release folder and type the following:

xattr -dr com.apple.quarantine textur

On Windows, you might have to unblock the exe by right-clicking the exe-file and check the Unblock checkbox.