CPImage

abstract class CPImage(origin: String) extends CPGameObject with CPAsset

Defines rectangular shape and its content as a collection of pixels.

Image is one of the key types in CosPlay. Almost everything that is drawn on the screen is represented by an image: FIGLet font string, sprites, video and animation frames, etc. Image itself is just a container for pixels. It can be created in-code or loaded and saved from and to the external file or resource. To render the image on the screen you can use CPCanvas.drawImage method.

Image is an asset. Just like other assets such as fonts, sounds, animations or videos they are not managed or governed by the CosPlay game engine unlike scenes and scene objects that are managed and governed by the game engine. Assets are typically created outside the game loop and managed by the developer, they can be freely shared between scenes or scene objects as any other standard Scala objects.

In-Code Images

One of the convenient features of CosPlay is that images can be created & painted (a.k.a. skinned) right in code with very minimal gestalt. The easiest way is to use CPArrayImage class that provides utility methods to convert a margin-based Scala string into an image. For example:

import org.cosplay.*
import CPColor.*
import CPArrayImage.*
import CPPixel.*

object CPAlienImage extends CPArrayImage(
   prepSeq("""
       |    .  .
       |     \/
       |    (@@)
       | g/\_)(_/\e
       |g/\(=--=)/\e
       |    //\\
       |   _|  |_
     """),
   (ch, _, _) => ch&C_LIME
)

Another example with more sophisticated skinning:

import org.cosplay.*
import CPColor.*
import CPArrayImage.*
import CPPixel.*

object CPAmigaImage extends CPArrayImage(
   prepSeq("""
     |  .---------.
     |  |.-------.|
     |  ||>run#xx||
     |  ||xxxxxxx||
     |  |"-------'|
     |.-^---------^-.
     ||x---~xxxAMiGA|
     |"-------------'
   """),
   (ch, _, _) => ch match
       case ' ' => XRAY
       case c @ ('A' | 'M' | 'i' | 'G') => CPPixel(c, C_NAVY, C_WHITE)
       case c @ ('r' | 'u' | 'n' | '#') => c&C_GREEN_YELLOW
       case 'x' => CPPixel(' ', C_BLACK)
       case '>' => '>'&C_GREEN_YELLOW
       case '~' => '~'&C_ORANGE_RED
       case c => c&C_WHITE
)

Loading Images

You can load images from the external source like URL or file path in one of the following formats:

  • *.xp REXPaint XP format. This is a native binary format supported by REXPaint ASCII editor. This format supports full color information.
  • *.csv REXPaint CSV format. This format is natively exported by REXPaint ASCII editor and also supported by CosPlay to save an image with. This format supports full color information.
  • *.txt format. Image in this format is a simple *.txt file and it does not provide or store any color information.

Use one of the following methods from the companion object to load the image from file path, resources folder or URL:

  • load()
  • loadRexCsv()
  • loadRexXp()
  • loadTxt()

For example:

val speckImg = CPImage.load(
   "prefab/images/speck.xp",
   (px, _, _) => px.withBg(None) // Make background transparent.
)

Saving Images

You can save image to the local file path in the following format:

  • *.csv REXPaint CSV format. This format is natively exported by REXPaint ASCII editor and also supported by CosPlay to save an image with. This format supports full color information.
  • *.xp REXPaint XP format. This is a native format used by REXPaint ASCII editor and can be loaded by the REXPaint.This format supports full color information.
  • *.txt Text format. This format does not retain color inforation.

Use the following methods to save the image to the file path:

ASCII Art Online

There's a vast collection of existing ASCII art imagery online. Here's some of the main resources where you can find it:

Prefabs

CosPlay comes with a list of prefab image, animations and video clips. All of them are shipped with CosPlay and can be found in org.cosplay.prefabs package and its sub-packages.

ASCII Art Editors

REXPaint ASCII editor is an excellent free editor for ASCII art from the creator of the Cogmind game. REXPaint editor is highly recommended for images with non-trivial coloring.

Value parameters:
origin

The origin of the image like file path or URL.

Example:

See CPImageCarouselExample class for the example of using images.

See CPImageFormatsExample class for the example of using images.

Companion:
object
Source:
CPImage.scala
trait CPAsset
class Object
trait Matchable
class Any
object CPAardvarkImage.type
object CPAlienImage.type
object CPAlienPlanetImage.type
object CPAmigaImage.type
object CPArrowImage.type
object CPAstronaut1Image.type
object CPAstronaut2Image.type
object CPAtari2080STImage.type
object CPBananaImage.type
object CPBatImage.type
object CPBearImage.type
object CPBedImage.type
object CPBeetleImage.type
object CPBrickNImage.type
object CPBrickWImage.type
object CPCactusImage.type
object CPCalculatorImage.type
object CPCapsuleImage.type
object CPCarImage.type
object CPCastleImage.type
object CPCloudImage.type
object CPCrownImage.type
object CPCubesImage.type
object CPDogImage.type
object CPDolphinImage.type
object CPFlamingoImage.type
object CPGameBoyImage.type
object CPGingerbreadImage.type
object CPGlobeImage.type
object CPGrimReaperImage.type
object CPHelicopterImage.type
object CPIceCreamImage.type
object CPKnifeImage.type
object CPLanderImage.type
object CPMoon1Image.type
object CPMoon2Image.type
object CPMotorcycleImage.type
object CPMouseImage.type
object CPOceanLinerImage.type
object CPPlaneImage.type
object CPRocket1Image.type
object CPRocket2Image.type
object CPSatellite1Image.type
object CPSatellite2Image.type
object CPSatellite3Image.type
object CPSaturnImage.type
object CPShieldImage.type
object CPSkullImage.type
object CPSpaceShipImage.type
object CPSunGlassesImage.type
object CPSwordImage.type
object CPTelescopeImage.type
object CPTntImage.type
object CPTornadoImage.type
object CPTruckImage.type
object CPUmbrellaImage.type
object CPBikingAniImage.type
object CPBirdAniImage.type
object CPCubeAniImage.type
object CPCurveAniImage.type
object CPDancerAniImage.type
object CPHandAniImage.type
object CPPointManAniImage.type
object CPRunnerAniImage.type
object CPCircle1aImage.type
object CPCircle1bImage.type
object CPCircle1cImage.type
object CPCircle2aImage.type
object CPCircle2bImage.type
object CPCircle3Image.type
object CPCircle4Image.type
object CPCircle5Image.type
object CPCircle6Image.type
object CPCircle9Image.type

Value members

Abstract methods

Gets image dimension.

Gets image dimension.

Source:
CPImage.scala
def getPixel(x: Int, y: Int): CPPixel

Gets pixel at the given XY-coordinate.

Gets pixel at the given XY-coordinate.

Value parameters:
x

X-coordinate of the pixel.

y

Y-coordinate of the pixel.

Source:
CPImage.scala

Concrete methods

def antialias(isBlank: CPPixel => Boolean): CPImage

Antialiases solid ASCII art image returning new image. Works only for solid ASCII art. Algorithm is loosely based on https://codegolf.stackexchange.com/questions/5450/anti-aliasing-ascii-art.

Antialiases solid ASCII art image returning new image. Works only for solid ASCII art. Algorithm is loosely based on https://codegolf.stackexchange.com/questions/5450/anti-aliasing-ascii-art.

Here's an example of antialiasing a solid ASCII art shape:

      xx  xxx  xxx                         db  <xb  <xb
     xxxx  xxx  xxx                       dxxb  Yxb  Yxb
    xxxxxx  xxx  xxx                     dxxxxb  Yxb  Yxb
   xxx  xxx  xxx  xxx                   dxx  xxb  xxb  xxb
   xxxx xxx  xxx  xxx                   Yxxb xxF  xxF  xxF
    xxxxxx  xxx  xxx                     YxxxxF  dxF  dxF
     xxxx  xxx  xxx         ===>          YxxF  dxF  dxF
   x  xx  xxx  xxx  x                   ;  YF  dxF  dxF  ;
   xx    xxx  xxx  xx                   xb    dxF  dxF  dx
   xxx  xxx  xxx  xxx                   xxb  <xF  <xF  <xx
   xxxx  xxx  xxx  xx                   xxxb  Yxb  Yxb  Yx
   xxxxx  xxx  xxx  x                   Yxxx>  Yx>  Yx>  V
Value parameters:
isBlank

Function to determine if given pixel is blank for the purpose of antialiasing.

See also:
Source:
CPImage.scala
def copy(): CPImage

Makes a deep snapshot copy of the current image.

Makes a deep snapshot copy of the current image.

Source:
CPImage.scala
def copy(rect: CPRect): CPImage

Makes a deep snapshot copy of the subregion of the current image.

Makes a deep snapshot copy of the subregion of the current image.

Value parameters:
rect

Subregion to copy.

Source:
CPImage.scala
def exists(f: (CPPixel, Int, Int) => Boolean): Boolean

Tests if there is a pixel in this image for which given predicate would return true.

Tests if there is a pixel in this image for which given predicate would return true.

Value parameters:
f

Predicate to test.

Source:
CPImage.scala
def foreach(f: CPPixel => Unit): Unit

Loops over the pixels in image.

Loops over the pixels in image.

Value parameters:
f

Function to call on each pixel.

Source:
CPImage.scala
def getHeight: Int

Shortcut to get image height.

Shortcut to get image height.

Source:
CPImage.scala

Gets rectangle shape of this image.

Gets rectangle shape of this image.

Source:
CPImage.scala
def getWidth: Int

Shortcut to get image width.

Shortcut to get image width.

Source:
CPImage.scala
def h: Int

Shortcut to get image height.

Shortcut to get image height.

Source:
CPImage.scala

Flips this image horizontally returning a new image. Note that this method does only shallow copy and returned image will delegate to this image. Use copy method to get a full deep copy before calling this method to get a full new image.

Flips this image horizontally returning a new image. Note that this method does only shallow copy and returned image will delegate to this image. Use copy method to get a full deep copy before calling this method to get a full new image.

See also:
Source:
CPImage.scala
def isSameAs(img: CPImage): Boolean

Tests whether this and given images have the same dimensions and the same pixels in corresponding locations.

Tests whether this and given images have the same dimensions and the same pixels in corresponding locations.

Value parameters:
img

Image to test.

Source:
CPImage.scala
def loop(f: (CPPixel, Int, Int) => Unit): Unit

Loops over the pixels in image. Iteration over the pixels in this image will be horizontal first. In other words, given the pixels with the following coordinates:

Loops over the pixels in image. Iteration over the pixels in this image will be horizontal first. In other words, given the pixels with the following coordinates:

   +-----------------+
   |(0,0) (1,0) (2,0)|
   |(0,1) (1,1) (2,1)|
   |(0,2) (1,2) (2,2)|
   +-----------------+

this method will iterate in the following order:

   (0,0) (1,0) (2,0) (0,1) (1,1) (2,1) (0,2) (1,2) (2,2)
Value parameters:
f

Function to call on each pixel. Note that unlike standard foreach function, this function also takes pixel's XY-coordinate.

Source:
CPImage.scala
def loopHor(f: (CPPixel, Int, Int) => Unit): Unit

Loops over the pixels in image. Iteration over the pixels in this image will be horizontal first. In other words, given the pixels with the following coordinates:

Loops over the pixels in image. Iteration over the pixels in this image will be horizontal first. In other words, given the pixels with the following coordinates:

   +-----------------+
   |(0,0) (1,0) (2,0)|
   |(0,1) (1,1) (2,1)|
   |(0,2) (1,2) (2,2)|
   +-----------------+

this method will iterate in the following order:

   (0,0) (1,0) (2,0) (0,1) (1,1) (2,1) (0,2) (1,2) (2,2)
Value parameters:
f

Function to call on each pixel. Note that unlike standard foreach function, this function also takes pixel's XY-coordinate.

Source:
CPImage.scala
def loopVert(f: (CPPixel, Int, Int) => Unit): Unit

Loops over the pixels in image. Iteration over the pixels in this image will be vertical first. In other words, given the pixels with the following coordinates:

Loops over the pixels in image. Iteration over the pixels in this image will be vertical first. In other words, given the pixels with the following coordinates:

   +-----------------+
   |(0,0) (1,0) (2,0)|
   |(0,1) (1,1) (2,1)|
   |(0,2) (1,2) (2,2)|
   +-----------------+

this method will iterate in the following order:

   (0,0) (0,1) (0,2) (1,0) (1,1) (1,2) (2,0) (2,1) (2,2)
Value parameters:
f

Function to call on each pixel. Note that unlike standard foreach function, this function also takes pixel's XY-coordinate.

Source:
CPImage.scala
def replaceBg(isBgPx: CPPixel => Boolean, replacePx: CPPixel): CPImage

Detects all background pixels and replaces them with a given pixel returning new image.

Detects all background pixels and replaces them with a given pixel returning new image.

A pixel is considered to be a background pixel when:

  • It's satisfies given predicate
  • It's not equal to given replacement pixel
  • There's a path from it to the edge of the image through background pixels only

For example, a fully enclosed area of the image containing background pixels will NOT be considered a background as there's no path to the edge of the image without crossing a non-background pixels.

Value parameters:
isBgPx

Predicate determining if given pixel is a background pixel.

replacePx

Pixel to replace the detected background pixels.

See also:
Source:
CPImage.scala
def resizeByDim(newDim: CPDim, bgPx: CPPixel): CPImage

Crops and centers the image returning a new image instance. Given dimension can be bigger or smaller.

Crops and centers the image returning a new image instance. Given dimension can be bigger or smaller.

Value parameters:
bgPx

Background pixel in case of bigger dimension. Default value is CPPixel.XRAY.

newDim

Dimension to crop by.

See also:
Source:
CPImage.scala
def resizeByInsets(insets: CPInsets, bgPx: CPPixel): CPImage

Crops this image using given insets. Insets can be positive or negative.

Crops this image using given insets. Insets can be positive or negative.

Value parameters:
bgPx

Background pixel in case of bigger dimension. Default value is CPPixel.XRAY.

insets

Insets to crop by.

See also:
Source:
CPImage.scala
def saveRexCsv(path: String, bg: CPColor): Unit

Saves this image in REXPaint CSV format.

Saves this image in REXPaint CSV format.

Value parameters:
bg

Background color to replace in pixels with no background.

path

Local file path.

See also:
Source:
CPImage.scala
def saveRexCsv(file: File, bg: CPColor): Unit

Saves this image in REXPaint CSV format.

Saves this image in REXPaint CSV format.

Value parameters:
bg

Background color to replace in pixels with no background.

file

File instance.

See also:
Source:
CPImage.scala
def saveRexXp(path: String, bg: CPColor): Unit

Saves this image in REXPaint XP format.

Saves this image in REXPaint XP format.

Value parameters:
bg

Background color to replace in pixels with no background.

path

Local file path.

See also:
Source:
CPImage.scala
def saveRexXp(file: File, bg: CPColor): Unit

Saves this image in REXPaint XP format. Note that this is a native format used by REXPaint and images in this format can be loaded by REXPaint for editing.

Saves this image in REXPaint XP format. Note that this is a native format used by REXPaint and images in this format can be loaded by REXPaint for editing.

Value parameters:
bg

Background color to set in pixels that have no background defined.

file

File instance.

See also:
Source:
CPImage.scala
def saveTxt(file: File): Unit

Saves this image in *.txt format. Note that this format does not retain the color information.

Saves this image in *.txt format. Note that this format does not retain the color information.

Value parameters:
file

File instance.

Source:
CPImage.scala
def saveTxt(path: String): Unit

Saves this image in *.txt format. Note that this format does not retain the color information.

Saves this image in *.txt format. Note that this format does not retain the color information.

Value parameters:
path

Local file path.

Source:
CPImage.scala
def skin(f: (CPPixel, Int, Int) => CPPixel): CPImage

Creates shallow copy of this image with given skin function. Note that this method will wrap this image and delegate to it instead of creating a full copy of the image. To make a deep copy use copy method.

Creates shallow copy of this image with given skin function. Note that this method will wrap this image and delegate to it instead of creating a full copy of the image. To make a deep copy use copy method.

Value parameters:
f

Skinning function. The function takes an existing pixel, its X and Y coordinate and return a new pixel.

See also:
Source:
CPImage.scala
def split(w: Int, h: Int): Seq[CPImage]

Splits this image into sequence of [w,h] images.

Splits this image into sequence of [w,h] images.

Value parameters:
h

Split height.

w

Split width.

Source:
CPImage.scala

Attaches given image underneath this image returning a new combined image.

Attaches given image underneath this image returning a new combined image.

Value parameters:
bgPx

Background pixel to use when combined image has large width.

img

Image to attached.

Source:
CPImage.scala

Attaches given image to the right of this image returning a new combined image.

Attaches given image to the right of this image returning a new combined image.

Value parameters:
bgPx

Background pixel to use when combined image has large height.

img

Image to attached.

Source:
CPImage.scala

Converts this image into 2D array of pixels.

Converts this image into 2D array of pixels.

Source:
CPImage.scala
def trim(isBlank: CPPixel => Boolean): CPImage

Trims blank rows and columns from this image returning a new, trimmed image.

Trims blank rows and columns from this image returning a new, trimmed image.

Value parameters:
isBlank

Function to determine if an individual pixel is blank. Row or column is blank if all of its pixels satisfy this predicate.

Source:
CPImage.scala

A shortcut method that considers all pixels with ' ' (space) character as background pixels and replaces them with CPPixel.XRAY returning a new image. This effectively makes the background transparent.

A shortcut method that considers all pixels with ' ' (space) character as background pixels and replaces them with CPPixel.XRAY returning a new image. This effectively makes the background transparent.

This is equivalent to:

   replaceBg(_.char == ' ', CPPixel.XRAY)
See also:
Source:
CPImage.scala
def trimBg(isBgPx: CPPixel => Boolean): CPImage

A shortcut method that detects background pixels and replaces them with CPPixel.XRAY returning a new image. This effectively makes the background transparent.

A shortcut method that detects background pixels and replaces them with CPPixel.XRAY returning a new image. This effectively makes the background transparent.

This is equivalent to:

   replaceBg(isBgPx, CPPixel.XRAY)
Value parameters:
isBgPx

Predicate determining if given pixel is a background pixel.

See also:
Source:
CPImage.scala

Flips this image vertically returning a new image. Note that this method does only shallow copy and returned image will delegate to this image. Use copy method to get a full deep copy before calling this method to get a full new image.

Flips this image vertically returning a new image. Note that this method does only shallow copy and returned image will delegate to this image. Use copy method to get a full deep copy before calling this method to get a full new image.

See also:
Source:
CPImage.scala
def w: Int

Shortcut to get image width.

Shortcut to get image width.

Source:
CPImage.scala

Inherited methods

override def equals(obj: Any): Boolean
Definition Classes
Inherited from:
CPGameObject
Source:
CPGameObject.scala
def getId: String

Gets unique ID of this game object.

Gets unique ID of this game object.

Inherited from:
CPGameObject
Source:
CPGameObject.scala
def getTags: Set[String]

Gets optional set of organizational tags. Note that by default the set of tags is empty.

Gets optional set of organizational tags. Note that by default the set of tags is empty.

See also:
Inherited from:
CPGameObject
Source:
CPGameObject.scala

Concrete fields

override val getOrigin: String

Gets the origin of this asset. Typically, this should be a URL, file name or class name for in-code assets like array images, animations or system font.

Gets the origin of this asset. Typically, this should be a URL, file name or class name for in-code assets like array images, animations or system font.

Source:
CPImage.scala
override val toString: String