Pixels & Colors

Pixel

In CosPlay, a pixel is a single character defined by CPPixel class. Character-pixel is a fundamental graphics unit in ASCII-based games. Just like the raster pixel on a graphics screen it represents the smallest area that can be rendered on the screen:

• CPPixel is immutable, once created it cannot be changed.
• A pixel contains a character from the ASCII character set.
• A pixel has foreground color.
• A pixel has optional background color. If not provided, the background is transparent.
• A pixel also has a tag that can be used for marking the pixel.

Note that pixel itself does not have a Z-index as it can be rendered at any Z-index.

Creating A Pixel

Pixel creation and manipulation is used extensively throughout a CosPlay game. There are several ways you can create a pixel:

• You can use various CPPixel constructors directly:

                      import org.cosplay.*
                      import CPColor.*
                      import CPPixel.*
  
                      // Canonical black 'x' on white background.
                      new CPPixel('x', C_BLACK, Some(C_WHITE), 0)
  
                      // Few companion object shortcuts for often used cases...
                      CPPixel('x', C_BLACK, C_WHITE) // Avoiding 'Some'.
                      CPPixel('x', C_BLACK) // Skipping background all together.
                      CPPixel('x', C_BLACK, 2) // Skipping background & setting a '2' ag.
                      CPPixel('x', C_BLACK, C_WHITE, 2) // Setting up a '2' tag.
                  

• You can also use a convenient syntactic sugar & and && based on extension of Char type. The following unit test demonstrates that usage (line 5 and line 19). Note that usage of & and && extension operators is the recommended way and that is what is used internally by CosPlay:

                      import org.cosplay.*
                      import CPColor.*
                      import CPPixel.*
  
                      val p1 = 'x'&C_BLACK // Recommended way.
                      val p2 = CPPixel('x', C_BLACK)
                      val p3 = new CPPixel('x', C_BLACK, None, 0)
  
                      assertTrue(p1 == p2)
                      assertTrue(p2 == p3)
  
                      val p6 = 'x'&&(C_BLACK, C_WHITE) // Recommended way.
                      val p7 = new CPPixel('x', C_BLACK, Option(C_WHITE), 0)
  
                      assertTrue(p6 == p7)
                  

  Using & and && extension operator is the recommended way to create pixels:

                          val px1 = 'x'&C_BLACK // Without background color.
                          val px2 = 'x'&&(C_BLACK, C_WHITE) // With background color.
                      

Modifying The Pixel

Since the pixel itself is immutable, to modify it you can use the following cloning methods:

            val p1 = 'x'&C_BLACK

            val p2 = p1.withFg(C_BLUE) // New pixel clone with given foreground.
            val p3 = p1.withBg(Option(C_HOT_PINK))) // New pixel clone with given background.
            val p4 = p1.withFgBg(C_BLUE, Option(C_HOT_PINK))) // Combines two above.
            val p5 = p1.withChar('z') // New pixel clone with given character.
            val p6 = p1.toLower // New pixel clone with character converted to lower case.
            val p7 = p1.toUpper // New pixel clone with character converted to upper case.
            val p8 = p1.withTag(10) // New pixel clone with given tag.
        

Color

In CosPlay, a color is defined by CPColor class:

• CPColor is immutable, once created it cannot be changed.
• A color contains RGB (Red, Green, Blue) and HSB (Hue, Saturation, Brightness) components.
• A color provides cloning methods for several B&W conversions.
• A color provides cloning methods for gradients and brightness transitions.
• A color provides methods for xterm color transcoding.

Creating A Color

CPColor companion object provides 100s of the pre-built color constants for all xterm and X11 standard colors. New color creation is an expensive process. It is highly recommended using one of the many built-in color constants or pre-create the colors you need upfront. As a rule of thumb - avoid new color creation on each frame update.

New colors can be created in the following ways:

            val c1 = CPColor(0, 128, 0) // RGB values.
            val c2 = CPColor("0x008000") // Hexadecimal RGB.
            val c3 = CPColor("#008000") // CSS-style hexadecimal RGB.

            assert(c1 == c2)
            assert(c2 == c3)
        

Modifying The Color

Since the color itself is immutable, to modify it you can use the following methods:

            val c = CPColor(32, 64, 128)

            val c1 = c.bw() // B&W clone.
            val c2 = c.bw() // Another B&W clone for lighter green and deeper blues.
            val c3 = c.awt // Standard AWT colors.
            val c4 = c.bgAnsi // ANSI background color sequence.
            val c5 = c.fgAnsi // ANSI foreground color sequence.
            val c6 = c.darker(0.5) // 50% darker clone.
            val c7 = c.lighter(0.5) // 50% lighter clone.
            val c8 = c.transform(0.2, 0.8, 0.5) // RGB-transformed clone.
            val c9 = c.color8Bit // 8-bit translation clone.

            // Gradient 20-step function between two colors.
            val f1 = CPColor.gradientFun(C_WHITE, C_BLACK, 20)
            // Gradient 20-step sequence between two colors.
            val s1 = CPColor.gradientSeq(C_WHITE, C_BLACK, 20)
        

8-Bit & 24-Bit Color Depth

Most modern ANSI terminals support "True Color" 24-bit colors, the unlimited combination of Red, Green, and Blue values in RGB. Some older terminals, however, only provide support for 8-bit colors where each color is a lookup number into 256-color lookup table (LUT). These are also often called xterm colors despite the fact that xterm terminal application does support the 24-bit colors. Note that there's only an approximate translation from a true 24-bit color to 8-bit color, i.e. the closest 8-bit color will be used when translating from 24-bit color to 8-bit color. More specifically, many darker 24-bit colors will convert as 8-bit dark grey.

By default, CosPlay stores all colors in 24-bit format internally and renders all colors as 24-bit colors in both native terminal and the built-in terminal emulator. If, however, you want to automatically convert 24-bit color to the nearest 8-bit color during rendering you need to set JVM system property COSPLAY_FORCE_8BIT_COLOR=true. Note that this will force both native terminal and built-in terminal emulator to use 8-bit color conversion even though technically the built-in terminal emulator can always display true 24-bit color. This is only necessary if running the game in the native terminal that does not support 24-bit colors.

Note also that since 8-bit color space is much smaller many color effects like fade in and fade out, color gradients, etc. will look less smooth when using 8-bit colors.

XTerm & X11 Color Names

CPColor companion object provides constants for pre-built colors:

• Names starting with C_ represent colors in xterm naming convention.
• Names starting with C_X11_ represent colors in X11 color naming convention.
• Names starting with CS_X11_ represent colors grouped by the primary color in X11 color naming convention.

You are free to use any constants with any naming convention, as well as mix and match - they are all just colors. Note that although there are many similar and identical colors across two naming groups, they do differ in some as well as offer some unique colors. CosPlay provides these two sets of constants for convenience. Please, refer to the following links for specific color references:

• https://www.ditig.com/256-colors-cheat-sheet for xterm color LUT.
• https://en.wikipedia.org/wiki/X11_color_names for X11 color names.
• https://en.wikipedia.org/wiki/ANSI_escape_code#Colors for 8-bit and 24-bit colors.

CosPlay XTerm LUT

Here's the lookup table for built-in xterm colors:

CosPlay X11 LUT

Here's the lookup table for built-in X11 colors: