CPImageSprite

org.cosplay.CPImageSprite
See theCPImageSprite companion object
class CPImageSprite(id: String, x: Int, y: Int, z: Int, img: CPImage, collidable: Boolean, shaders: Seq[CPShader], tags: Set[String]) extends CPDynamicSprite

Scene object tailor-made for rendering images.

This sprite can be used to render static or moving image, the same image or changing images. For static unchanging images see CPStaticImageSprite for even simpler API.

Dynamic Image Position

If a game is intended to work with adaptive scene sizing than all of its scene objects must adapt to changing size of the scene. Image sprite provides simple and convenient way to support this logic. Here's an example of using image sprite to display an image at the center of the screen dynamically adjusting its position on each frame to the actual canvas size:

   val img = ...
   val spr = new CPImageSprite("logo", 0, 0, 0, img):
       override def update(ctx: CPSceneObjectContext): Unit =
           val canv = ctx.getCanvas
           setX((canv.dim.width - getImage.getWidth) / 2)
           setY((canv.dim.height - getImage.getHeight) / 2)

Notes:

  • All we have to do is override CPSceneObject.update method to update XY-coordinate on each frame.
  • Canvas instance will always have the current size of scene: whether it is defined explicitly or implicitly as the current size of the terminal.
  • Initial (0,0) position is not used as we override the actual position on each frame.
  • We use methods setX and setY to set current XY-coordinates.
  • Note that we don't need to override any other methods. Specifically, we don't need to override render method since it relies on getX and getY method in its implementation.

See also CPDynamicSprite and CPLayoutSprite for imperative scene object layout.

Sprites

CosPlay provides number of built-in sprites. A sprite is a scene objects, fully or partially visible including being entirely off-screen, that is custom designed for a particular use case. Built-in sprites provide concrete implementations for the abstract methods in the base CPSceneObject class. Most non-trivial games will use combination of the built-in sprites and their own ones. Here's the list of some of the built-in sprites:

Value parameters

collidable

Whether or not this sprite has a collision shape. Default is false.

id

Optional ID of the sprite. By default, a random ID will be used.

img

The image to render. It can be changed later.

shaders

Optional sequence of shaders for this sprite. Default value is an empty sequence.

tags

Optional set of organizational or grouping tags. By default, the empty set is used.

x

Initial X-coordinate of the sprite. Default value is zero.

y

Initial Y-coordinate of the sprite. Default value is zero.

z

Initial z-index at which to render the image. Default value is zero.

Attributes

See also

CPSceneObjectContext.getCanvas to get current canvas you can draw on.

CPCanvas various API to draw on the canvas.

Example

See CPImageCarouselExample class for the example of using images.

See CPImageFormatsExample class for the example of using images.

Companion
object
Source
CPImageSprite.scala
Graph
Supertypes
trait CPLifecycle
class CPGameObject
class Object
trait Matchable
class Any
Show all
Known subtypes

Members list

Value members

Concrete methods

override def getDim: CPDim

Gets current dimension (width and height) of this object.

Gets current dimension (width and height) of this object.

Attributes

Definition Classes
Source
CPImageSprite.scala

Gets current image to render.

Gets current image to render.

Attributes

Returns

Current image to render.

Source
CPImageSprite.scala
override def getRect: CPRect

Gets rectangular shape of this sprite. It is basically a combination of its top-left corner XY-coordinate and sprite's dimension.

Gets rectangular shape of this sprite. It is basically a combination of its top-left corner XY-coordinate and sprite's dimension.

Attributes

Definition Classes
Source
CPImageSprite.scala
override def render(ctx: CPSceneObjectContext): Unit

Called to render this scene object. Only visible and in camera frame objects will receive this callback. This callback is called on scene object after all scene objects received update and monitor callbacks. Note that unlike update and monitor callbacks and shaders that are called for all scene objects on each frame, this callback is only called for scene objects that are visible and, at least partially, in camera frame. The order in which scene objects are called is undefined.

Called to render this scene object. Only visible and in camera frame objects will receive this callback. This callback is called on scene object after all scene objects received update and monitor callbacks. Note that unlike update and monitor callbacks and shaders that are called for all scene objects on each frame, this callback is only called for scene objects that are visible and, at least partially, in camera frame. The order in which scene objects are called is undefined.

Note that generally this callback should not modify scene object state (which should be done in either update or monitor callbacks.

Default implementation is no-op.

Attributes

Definition Classes
Source
CPImageSprite.scala
def reset(): Unit

Resets this sprite to its initial XYZ-coordinates and the initial image.

Resets this sprite to its initial XYZ-coordinates and the initial image.

Attributes

Source
CPImageSprite.scala
def setImage(img: CPImage): Unit

Changes the image this sprite is rendering.

Changes the image this sprite is rendering.

Value parameters

img

New image to render.

Attributes

Source
CPImageSprite.scala

Inherited methods

override def equals(obj: Any): Boolean

Compares the receiver object (this) with the argument object (that) for equivalence.

Compares the receiver object (this) with the argument object (that) for equivalence.

Any implementation of this method should be an equivalence relation:

  • It is reflexive: for any instance x of type Any, x.equals(x) should return true.
  • It is symmetric: for any instances x and y of type Any, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any instances x, y, and z of type Any if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.

If you override this method, you should verify that your implementation remains an equivalence relation. Additionally, when overriding this method it is usually necessary to override hashCode to ensure that objects which are "equal" (o1.equals(o2) returns true) hash to the same scala.Int. (o1.hashCode.equals(o2.hashCode)).

Value parameters

that

the object to compare against this object for equality.

Attributes

Returns

true if the receiver object is equivalent to the argument; false otherwise.

Definition Classes
CPGameObject -> Any
Inherited from:
CPGameObject
Source
CPGameObject.scala
override def getCollisionRect: Option[CPRect]

Gets optional collision shape or hit box for this sprite.

Gets optional collision shape or hit box for this sprite.

Attributes

Definition Classes
Inherited from:
CPDynamicSprite
Source
CPDynamicSprite.scala
inline def getHeight: Int

Gets current height of this object.

Gets current height of this object.

Attributes

See also
Inherited from:
CPSceneObject
Source
CPSceneObject.scala
def getId: String

Gets unique ID of this game object.

Gets unique ID of this game object.

Attributes

Inherited from:
CPGameObject
Source
CPGameObject.scala
override def getShaders: Seq[CPShader]

Gets the optional list of shaders attached to this scene object. By default, returns an empty list. Note that shaders are called regardless of whether the object visible, in camera frame or invisible.

Gets the optional list of shaders attached to this scene object. By default, returns an empty list. Note that shaders are called regardless of whether the object visible, in camera frame or invisible.

Attributes

Definition Classes
Inherited from:
CPDynamicSprite
Source
CPDynamicSprite.scala
final def getState: State

Gets current lifecycle state.

Gets current lifecycle state.

Attributes

Inherited from:
CPLifecycle
Source
CPLifecycle.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.

Attributes

See also
Inherited from:
CPGameObject
Source
CPGameObject.scala
inline def getWidth: Int

Gets current width of this object.

Gets current width of this object.

Attributes

See also
Inherited from:
CPSceneObject
Source
CPSceneObject.scala
override def getX: Int

Gets current X-coordinate of this object within dimensions of its scene. Note that returned value is allowed to be outside scene's dimension (e.g. negative value). In such cases, the clipping of the scene rendering will result in showing only portion or none of the object.

Gets current X-coordinate of this object within dimensions of its scene. Note that returned value is allowed to be outside scene's dimension (e.g. negative value). In such cases, the clipping of the scene rendering will result in showing only portion or none of the object.

Attributes

Definition Classes
Inherited from:
CPDynamicSprite
Source
CPDynamicSprite.scala
inline def getX2: Int

Gets last X-coordinate which is

Gets last X-coordinate which is

getX + getWidth - 1

. Note the value when the width is zero.

Attributes

Returns

Last X-coordinate for this sprite.

Inherited from:
CPSceneObject
Source
CPSceneObject.scala
override def getY: Int

Gets current Y-coordinate of this object within dimensions of its scene. Note that returned value is allowed to be outside scene's dimension (e.g. negative value). In such cases, the clipping of the scene rendering will result in showing only portion or none of the object.

Gets current Y-coordinate of this object within dimensions of its scene. Note that returned value is allowed to be outside scene's dimension (e.g. negative value). In such cases, the clipping of the scene rendering will result in showing only portion or none of the object.

Attributes

Definition Classes
Inherited from:
CPDynamicSprite
Source
CPDynamicSprite.scala
inline def getY2: Int

Gets last Y-coordinate which is

Gets last Y-coordinate which is

getY + getHeight - 1

. Note the value when the height is zero.

Attributes

Returns

Last Y-coordinate for this sprite.

Inherited from:
CPSceneObject
Source
CPSceneObject.scala
override def getZ: Int

Gets Z-index or order to use in rendering of this object. A pixel with higher Z-index visually overrides the overlapping pixel in the same XY-coordinate with equal or smaller Z-index.

Gets Z-index or order to use in rendering of this object. A pixel with higher Z-index visually overrides the overlapping pixel in the same XY-coordinate with equal or smaller Z-index.

Attributes

Definition Classes
Inherited from:
CPDynamicSprite
Source
CPDynamicSprite.scala
def hide(): Unit

Shortcut method for hiding this object. Note that by default all scene objects are visible. Note also that this change happens immediately in the same frame. If you want this to happen in the next frame only you need to use CPSceneObjectContext.runNextFrame.

Shortcut method for hiding this object. Note that by default all scene objects are visible. Note also that this change happens immediately in the same frame. If you want this to happen in the next frame only you need to use CPSceneObjectContext.runNextFrame.

Attributes

See also
Inherited from:
CPSceneObject
Source
CPSceneObject.scala
def incrX(d: Int): Unit

Increments current X-coordinate by given value.

Increments current X-coordinate by given value.

Value parameters

d

A value (negative, zero or positive) to increment X-coordinate by.

Attributes

Inherited from:
CPDynamicSprite
Source
CPDynamicSprite.scala
def incrY(d: Int): Unit

Increments current Y-coordinate by given value.

Increments current Y-coordinate by given value.

Value parameters

d

A value (negative, zero or positive) to increment Y-coordinate by.

Attributes

Inherited from:
CPDynamicSprite
Source
CPDynamicSprite.scala
def isVisible: Boolean

Checks the visibility flag.

Checks the visibility flag.

If object is invisible than only update method will be called on each frame. If object is visible and in camera frame - method render will be called as well to render itself. Note that shaders are called regardless of whether the object visible, in camera frame or invisible.

Attributes

See also
Inherited from:
CPSceneObject
Source
CPSceneObject.scala
def monitor(ctx: CPSceneObjectContext): Unit

Called after all scene objects have been updated but before any of them were rendered. It allows, for example, to rearrange UI sprites on the screen after all of them had a chance to update their dimensions but before they are actually rendered on the screen. Essentially, it provides for "post-update, pre-render" notification. The order in which scene objects are called is undefined.

Called after all scene objects have been updated but before any of them were rendered. It allows, for example, to rearrange UI sprites on the screen after all of them had a chance to update their dimensions but before they are actually rendered on the screen. Essentially, it provides for "post-update, pre-render" notification. The order in which scene objects are called is undefined.

Note that in most cases one should not override this callback. It is only meant for the use cases when one needs to be notified when all scene objects to be updated but before any of them are rendered. Default implementation is no-op. No rendering should be done in this callback.

Default implementation is no-op.

Value parameters

ctx

Frame context. This context provides bulk of functionality that a scene object can do in a game, e.g. interact with other scene objects, check collisions, read input events and manage input focus, add or remove scene objects, add new and switch between scenes, etc.

Attributes

See also
Inherited from:
CPSceneObject
Source
CPSceneObject.scala
def onActivate(): Unit

Callback on lifecycle object activation. Default implementation is no-op.

Callback on lifecycle object activation. Default implementation is no-op.

Attributes

See also

CPLifecycle.State.LF_ACTIVE

Inherited from:
CPLifecycle
Source
CPLifecycle.scala
def onDeactivate(): Unit

Callback on lifecycle object deactivation. Default implementation is no-op.

Callback on lifecycle object deactivation. Default implementation is no-op.

Attributes

See also

CPLifecycle.State.LF_INACTIVE

Inherited from:
CPLifecycle
Source
CPLifecycle.scala
def onStart(): Unit

Callback on lifecycle object start. Default implementation is no-op.

Callback on lifecycle object start. Default implementation is no-op.

Attributes

See also

CPLifecycle.State.LF_STARTED

Inherited from:
CPLifecycle
Source
CPLifecycle.scala
def onStop(): Unit

Callback on lifecycle object stop. Default implementation is no-op.

Callback on lifecycle object stop. Default implementation is no-op.

Attributes

See also

CPLifecycle.State.LF_STOPPED

Inherited from:
CPLifecycle
Source
CPLifecycle.scala
def resetXY(): Unit

Resets this sprite to its initial XYZ-coordinates.

Resets this sprite to its initial XYZ-coordinates.

Attributes

Inherited from:
CPDynamicSprite
Source
CPDynamicSprite.scala
def resetXYZ(): Unit

Resets this sprite to its initial XY-coordinates.

Resets this sprite to its initial XY-coordinates.

Attributes

Inherited from:
CPDynamicSprite
Source
CPDynamicSprite.scala
def setVisible(vis: Boolean): Unit

Sets visibility flag. Note that by default all scene objects are visible. Note also that this change happens immediately in the same frame. If you want this to happen in the next frame only you need to use CPSceneObjectContext.runNextFrame.

Sets visibility flag. Note that by default all scene objects are visible. Note also that this change happens immediately in the same frame. If you want this to happen in the next frame only you need to use CPSceneObjectContext.runNextFrame.

Value parameters

vis

true to make this object visible, false otherwise.

Attributes

See also
Inherited from:
CPSceneObject
Source
CPSceneObject.scala
def setX(d: Int): Unit

Sets current X-coordinate. This coordinate will be returned from getX method.

Sets current X-coordinate. This coordinate will be returned from getX method.

Value parameters

d

X-coordinate to set.

Attributes

Inherited from:
CPDynamicSprite
Source
CPDynamicSprite.scala
def setXY(a: Int, b: Int): Unit

Sets both current XY-coordinates.

Sets both current XY-coordinates.

Value parameters

a

X-coordinate to set.

b

Y-coordinate to set.

Attributes

Inherited from:
CPDynamicSprite
Source
CPDynamicSprite.scala
def setXYZ(a: Int, b: Int, z: Int): Unit

Sets both current XY-coordinates as wel as z-index.

Sets both current XY-coordinates as wel as z-index.

Value parameters

a

X-coordinate to set.

b

Y-coordinate to set.

z

Z-index to set.

Attributes

Inherited from:
CPDynamicSprite
Source
CPDynamicSprite.scala
def setY(d: Int): Unit

Sets current Y-coordinate. This coordinate will be returned from getY method.

Sets current Y-coordinate. This coordinate will be returned from getY method.

Value parameters

d

Y-coordinate to set.

Attributes

Inherited from:
CPDynamicSprite
Source
CPDynamicSprite.scala
def setZ(z: Int): Unit

Sets current z-index. This index will be returned from getZ method.

Sets current z-index. This index will be returned from getZ method.

Value parameters

z

Z-index to set.

Attributes

Inherited from:
CPDynamicSprite
Source
CPDynamicSprite.scala
def show(): Unit

Shortcut method for showing this object. Note that by default all scene objects are visible. Note also that this change happens immediately in the same frame. If you want this to happen in the next frame only you need to use CPSceneObjectContext.runNextFrame.

Shortcut method for showing this object. Note that by default all scene objects are visible. Note also that this change happens immediately in the same frame. If you want this to happen in the next frame only you need to use CPSceneObjectContext.runNextFrame.

Attributes

See also
Inherited from:
CPSceneObject
Source
CPSceneObject.scala
def update(ctx: CPSceneObjectContext): Unit

Called to update the internal state of this scene object. This callback is called each frame on every object in the scene and it is called before any render callback. Note that all scene object will receive this callback before first render callback. The order in which scene objects are called is undefined.

Called to update the internal state of this scene object. This callback is called each frame on every object in the scene and it is called before any render callback. Note that all scene object will receive this callback before first render callback. The order in which scene objects are called is undefined.

Default implementation is no-op. No rendering should be done in this callback.

Value parameters

ctx

Frame context. This context provides bulk of functionality that a scene object can do in a game, e.g. interact with other scene objects, check collisions, read input events and manage input focus, add or remove scene objects, add new and switch between scenes, etc.

Attributes

See also
Inherited from:
CPSceneObject
Source
CPSceneObject.scala

Concrete fields

Initial image of the sprite.

Initial image of the sprite.

Attributes

See also
Source
CPImageSprite.scala

Inherited fields

val initX: Int

Initial X-coordinate of the sprite.

Initial X-coordinate of the sprite.

Attributes

See also
Inherited from:
CPDynamicSprite
Source
CPDynamicSprite.scala
val initY: Int

Initial Y-coordinate of the sprite.

Initial Y-coordinate of the sprite.

Attributes

See also
Inherited from:
CPDynamicSprite
Source
CPDynamicSprite.scala
val initZ: Int

Initial Z-index of the sprite.

Initial Z-index of the sprite.

Attributes

See also
Inherited from:
CPDynamicSprite
Source
CPDynamicSprite.scala