Class Layer
- All Implemented Interfaces:
AutoCloseable
,Closeable
- Direct Known Subclasses:
ClippedLayer
,ImageLayer
paint(playn.core.Surface)
ed.
Everything can be accomplished by extending Layer
and overriding paintImpl(playn.core.Surface)
.
However, GroupLayer
, ImageLayer
, ClippedLayer
etc. are provided to
make it easy to implement common use cases "out of the box".
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic interface
Used to customize a layer's hit testing mechanism.static enum
Used to configure the origin of a layer based on its width/height.static enum
Enumerates layer lifecycle states; seestate
.static interface
Nested classes/interfaces inherited from interface react.Closeable
Closeable.Set, Closeable.Util
-
Field Summary
Modifier and TypeFieldDescriptionstatic boolean
Controls rendering of debug rectangles around views.final ValueView<Layer.State>
A reactive value which tracks this layer's lifecycle. -
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionConfigures a hit tester for this layer which hits this layer any time a hit does not hit a child of this layer.float
alpha()
Return the global alpha value for this layer.void
close()
Disposes this layer, removing it from its parent layer.void
debugPrint
(Log log) Prints a debug representation of this layer and its children.float
depth()
Returns this layer's current depth.boolean
disposed()
Whether this layer has been disposed.events()
Returns a signal via which events may be dispatched "on" this layer.boolean
Returns true ifevents
has at least one listener.float
height()
Returns the height of this layer.Tests whether the supplied (layer relative) point "hits" this layer or any of its children.LikehitTest(pythagoras.f.Point)
except that it ignores a configuredLayer.HitTester
.boolean
Returns whether this layer reacts to clicks and touches.name()
Returns the name of this layer.void
onAdded
(SignalView.Listener<? super Layer> action) Connectsaction
tostate
such that it is triggered when this layer is added to a rooted scene graph.void
onDisposed
(SignalView.Listener<? super Layer> action) Connectsaction
tostate
such that it is triggered when this layer is disposed.void
onRemoved
(SignalView.Listener<? super Layer> action) Connectsaction
tostate
such that it is triggered when this layer is removed from a rooted scene graph.Writes this layer's origin intointo
.Writes this layer's origin intointo
.float
originX()
Returns the x-component of the layer's origin.float
originY()
Returns the y-component of the layer's origin.final void
Renders this layer tosurf
, including its children.parent()
Returns the layer that contains this layer, ornull
.float
rotation()
Returns this layer's current rotation.Writes this layer's scale intointo
.float
Returns the height of the layer multiplied by its y scale.float
Returns the width of the layer multiplied by its x scale.float
scaleX()
Returns this layer's current scale in the x direction.float
scaleY()
Returns this layer's current scale in the y direction.setAlpha
(float alpha) Sets the alpha component of this layer's current tint.Configures a custom batch (i.e.setDepth
(float depth) Sets the depth of this layer.setHitTester
(Layer.HitTester tester) Configures a custom hit tester for this layer.setInteractive
(boolean interactive) Configures this layer as reactive to clicks and touches, or not.Sets the name of this layer.setOrigin
(float x, float y) Sets the origin of the layer to a fixed position.setOrigin
(Layer.Origin origin) Configures the origin of this layer based on a logical location which is recomputed whenever the layer changes size.setRotation
(float angle) Sets the current rotation of this layer, in radians.setScale
(float scale) Sets the current x and y scale of this layer toscale
..setScale
(float sx, float sy) Sets the current x and y scale of this layer.setScaleX
(float sx) Sets the current x scale of this layer.setScaleY
(float sy) Sets the current y scale of this layer.setTint
(int tint) Sets the tint for this layer, asARGB
.setTranslation
(float x, float y) Sets the x and y translation of this layer.setTranslation
(XY trans) A variant ofsetTranslation(float,float)
that takes anXY
.setTx
(float x) Sets the x translation of this layer.setTy
(float y) Sets the y translation of this layer.setVisible
(boolean visible) Configures this layer's visibility: if true, it will be rendered as normal, if false it and its children will not be rendered.int
tint()
Returns the current tint for this layer, asARGB
.toString()
Returns the layer's current transformation matrix.translation
(Point into) Writes this layer's translation intointo
.translation
(Vector into) Writes this layer's translation intointo
.float
tx()
Returns this layer's current translation in the x direction.float
ty()
Returns this layer's current translation in the y direction.boolean
visible()
Returns true if this layer is visible (i.e.void
visit
(Layer.Visitor visitor) Visits this layer and its children, in depth first order, withvisitor
.float
width()
Returns the width of this layer.
-
Field Details
-
DEBUG_RECTS
public static boolean DEBUG_RECTSControls rendering of debug rectangles around views. -
state
A reactive value which tracks this layer's lifecycle. It starts outLayer.State.REMOVED
, and transitions toLayer.State.ADDED
when the layer is added to a scene graph root and back toLayer.State.REMOVED
when removed, until it is finallyclose()
d at which point it transitions toLayer.State.DISPOSED
.
-
-
Constructor Details
-
Layer
public Layer()Creates an unclipped layer. Thepaint(playn.core.Surface)
method must be overridden by the creator.
-
-
Method Details
-
name
Returns the name of this layer. This defaults to the simple name of the class, but can be set programmatically to aid in debugging. SeesetName(java.lang.String)
. -
setName
Sets the name of this layer. Seename
.- Returns:
- a reference to this layer for call chaining.
-
parent
Returns the layer that contains this layer, ornull
. -
events
Returns a signal via which events may be dispatched "on" this layer. TheDispatcher
mechanism uses this to dispatch (and listen for) mouse, pointer and touch events to the layers affected by them. A game can also use this to dispatch any other kinds of events on a per-layer basis, with the caveat that all listeners are notified of every event and each must do a type test on the event to determine whether it matches.Also, any layer that has one or more listeners on its events signal is marked as
interactive()
. Further, anyGroupLayer
which has one or more interactive children is also marked as interactive. This allowsDispatcher
s to be more efficient in their dispatching of UI events. -
hasEventListeners
public boolean hasEventListeners()Returns true ifevents
has at least one listener. Use this instead of callingReactor.hasConnections()
onevents
becauseevents
is created lazily this method avoids creating it unnecessarily. -
interactive
public boolean interactive()Returns whether this layer reacts to clicks and touches. If a layer is interactive, it will respond tohitTest(pythagoras.f.Point)
, which forms the basis for the click and touch processing provided by theDispatcher
s. -
setInteractive
Configures this layer as reactive to clicks and touches, or not. You usually don't have to do this automatically because a layer is automatically marked as interactive (along with all of its parents) when a listener is added to itsevents
signal.A
GroupLayer
will be made non-interactive automatically if an event is dispatched to it and it discovers that it no longer has any interactive children. Manual management of interactivity is thus generally only useful for "leaf" nodes in the scene graph.- Returns:
- a reference to this layer for call chaining.
-
visible
public boolean visible()Returns true if this layer is visible (i.e. it is being rendered). -
setVisible
Configures this layer's visibility: if true, it will be rendered as normal, if false it and its children will not be rendered.- Returns:
- a reference to this layer for call chaining.
-
disposed
public boolean disposed()Whether this layer has been disposed. If true, the layer can no longer be used. -
onAdded
Connectsaction
tostate
such that it is triggered when this layer is added to a rooted scene graph. -
onRemoved
Connectsaction
tostate
such that it is triggered when this layer is removed from a rooted scene graph. -
onDisposed
Connectsaction
tostate
such that it is triggered when this layer is disposed. -
close
public void close()Disposes this layer, removing it from its parent layer. Any resources associated with this layer are freed, and it cannot be reused after being disposed. Disposing a layer that has children will dispose them as well.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
-
transform
Returns the layer's current transformation matrix. If any changes have been made to the layer's scale, rotation or translation, they will be applied to the transform matrix before it is returned.Note: any direct modifications to this matrix except modifications to its translation, will be overwritten if a call is subsequently made to
setScale(float)
,setScale(float,float)
,setScaleX(float)
,setScaleY(float)
orsetRotation(float)
. If you intend to manipulate a layer's transform matrix directly, do not call those other methods. Also do not expectscaleX
,scaleY
, orrotation
to reflect the direct changes you've made to the transform matrix. They will not. -
alpha
public float alpha()Return the global alpha value for this layer.The global alpha value for a layer controls the opacity of the layer but does not affect the current drawing operation. I.e., when
Game.paint
is called and theLayer
is drawn, this alpha value is applied to the alpha channel of the Layer.By default, the alpha for a Layer is 1.0 (not transparent).
- Returns:
- alpha in range [0,1] where 0 is transparent and 1 is opaque
-
setAlpha
Sets the alpha component of this layer's current tint. Note that this value will be quantized to an integer between 0 and 255. Also seesetTint(int)
.Values outside the range [0,1] will be clamped to the range [0,1].
- Parameters:
alpha
- alpha value in range [0,1] where 0 is transparent and 1 is opaque.- Returns:
- a reference to this layer for call chaining.
-
tint
public int tint()Returns the current tint for this layer, asARGB
. -
setTint
Sets the tint for this layer, asARGB
.NOTE: this will overwrite any value configured via
setAlpha(float)
. Either include your desired alpha in the high bits oftint
or callsetAlpha(float)
after calling this method.NOTE: the RGB components of a layer's tint only work on GL-based backends. It is not possible to tint layers using the HTML5 canvas and Flash backends.
The tint for a layer controls the opacity of the layer but does not affect the current drawing operation. I.e., when
Game.paint
is called and theLayer
is drawn, this tint is applied when rendering the layer.- Returns:
- a reference to this layer for call chaining.
-
originX
public float originX()Returns the x-component of the layer's origin. -
originY
public float originY()Returns the y-component of the layer's origin. -
origin
Writes this layer's origin intointo
.- Returns:
into
for easy call chaining.
-
origin
Writes this layer's origin intointo
.- Returns:
into
for easy call chaining.
-
setOrigin
Sets the origin of the layer to a fixed position. This automatically sets the layer's logical origin toLayer.Origin.FIXED
.- Parameters:
x
- origin on x axis in display units.y
- origin on y axis in display units.- Returns:
- a reference to this layer for call chaining.
-
setOrigin
Configures the origin of this layer based on a logical location which is recomputed whenever the layer changes size.- Returns:
- a reference to this layer for call chaining.
-
depth
public float depth()Returns this layer's current depth. -
setDepth
Sets the depth of this layer.Within a single
GroupLayer
, layers are rendered from lowest depth to highest depth.- Returns:
- a reference to this layer for call chaining.
-
tx
public float tx()Returns this layer's current translation in the x direction. -
ty
public float ty()Returns this layer's current translation in the y direction. -
translation
Writes this layer's translation intointo
.- Returns:
into
for easy call chaining.
-
translation
Writes this layer's translation intointo
.- Returns:
into
for easy call chaining.
-
setTx
Sets the x translation of this layer.Note: all transform changes are deferred until
transform
is called (which happens during rendering, if not before) at which point the current scale, rotation and translation are composed into an affine transform matrix. This means that, for example, setting rotation and then setting scale will not flip the rotation like it would were these applied to the transform matrix one operation at a time.- Returns:
- a reference to this layer for call chaining.
-
setTy
Sets the y translation of this layer.Note: all transform changes are deferred until
transform
is called (which happens during rendering, if not before) at which point the current scale, rotation and translation are composed into an affine transform matrix. This means that, for example, setting rotation and then setting scale will not flip the rotation like it would were these applied to the transform matrix one operation at a time.- Returns:
- a reference to this layer for call chaining.
-
setTranslation
Sets the x and y translation of this layer.Note: all transform changes are deferred until
transform
is called (which happens during rendering, if not before) at which point the current scale, rotation and translation are composed into an affine transform matrix. This means that, for example, setting rotation and then setting scale will not flip the rotation like it would were these applied to the transform matrix one operation at a time.- Returns:
- a reference to this layer for call chaining.
-
setTranslation
A variant ofsetTranslation(float,float)
that takes anXY
. -
scaleX
public float scaleX()Returns this layer's current scale in the x direction.Note: this is the most recent value supplied to
setScale(float)
orsetScale(float,float)
, it is not extracted from the underlying transform. Thus the sign of the scale returned by this method is preserved. It's also substantially cheaper than extracting the scale from the affine transform matrix. This also means that if you change the scale directly on thetransform
that scale will not be returned by this method. -
scaleY
public float scaleY()Returns this layer's current scale in the y direction.Note: this is the most recent value supplied to
setScale(float)
orsetScale(float,float)
, it is not extracted from the underlying transform. Thus the sign of the scale returned by this method is preserved. It's also substantially cheaper than extracting the scale from the affine transform matrix. This also means that if you change the scale directly on thetransform
that scale will not be returned by this method. -
scale
Writes this layer's scale intointo
.- Returns:
into
for easy call chaining.
-
setScale
Sets the current x and y scale of this layer toscale
.. Note that a scale of1
is equivalent to no scale.Note: all transform changes are deferred until
transform
is called (which happens during rendering, if not before) at which point the current scale, rotation and translation are composed into an affine transform matrix. This means that, for example, setting rotation and then setting scale will not flip the rotation like it would were these applied to the transform matrix one operation at a time.- Parameters:
scale
- non-zero scale value.- Returns:
- a reference to this layer for call chaining.
-
setScaleX
Sets the current x scale of this layer. Note that a scale of1
is equivalent to no scale.Note: all transform changes are deferred until
transform
is called (which happens during rendering, if not before) at which point the current scale, rotation and translation are composed into an affine transform matrix. This means that, for example, setting rotation and then setting scale will not flip the rotation like it would were these applied to the transform matrix one operation at a time.- Parameters:
sx
- non-zero scale value.- Returns:
- a reference to this layer for call chaining.
-
setScaleY
Sets the current y scale of this layer. Note that a scale of1
is equivalent to no scale.Note: all transform changes are deferred until
transform
is called (which happens during rendering, if not before) at which point the current scale, rotation and translation are composed into an affine transform matrix. This means that, for example, setting rotation and then setting scale will not flip the rotation like it would were these applied to the transform matrix one operation at a time.- Parameters:
sy
- non-zero scale value.- Returns:
- a reference to this layer for call chaining.
-
setScale
Sets the current x and y scale of this layer. Note that a scale of1
is equivalent to no scale.Note: all transform changes are deferred until
transform
is called (which happens during rendering, if not before) at which point the current scale, rotation and translation are composed into an affine transform matrix. This means that, for example, setting rotation and then setting scale will not flip the rotation like it would were these applied to the transform matrix one operation at a time.- Parameters:
sx
- non-zero scale value for the x axis.sy
- non-zero scale value for the y axis.- Returns:
- a reference to this layer for call chaining.
-
rotation
public float rotation()Returns this layer's current rotation.Note: this is the most recent value supplied to
setRotation(float)
, it is not extracted from the underlying transform. Thus the value may lie outside the range [-pi, pi] and the most recently set value is preserved. It's also substantially cheaper than extracting the rotation from the affine transform matrix. This also means that if you change the scale directly on thetransform
that rotation will not be returned by this method. -
setRotation
Sets the current rotation of this layer, in radians. The rotation is done around the currently set origin, SeesetOrigin(float, float)
.Note: all transform changes are deferred until
transform
is called (which happens during rendering, if not before) at which point the current scale, rotation and translation are composed into an affine transform matrix. This means that, for example, setting rotation and then setting scale will not flip the rotation like it would were these applied to the transform matrix one operation at a time.- Parameters:
angle
- angle to rotate, in radians.- Returns:
- a reference to this layer for call chaining.
-
width
public float width()Returns the width of this layer. Note: not all layers know their size. Those that don't return 0. -
height
public float height()Returns the height of this layer. Note: not all layers know their size. Those that don't return 0. -
scaledWidth
public float scaledWidth()Returns the width of the layer multiplied by its x scale. Note: not all layers know their size. Those that don't return 0. -
scaledHeight
public float scaledHeight()Returns the height of the layer multiplied by its y scale. Note: not all layers know their size. Those that don't return 0. -
hitTest
Tests whether the supplied (layer relative) point "hits" this layer or any of its children. By default a hit is any point that falls in a layer's bounding box. A group layer checks its children for hits.Note that this method mutates the supplied point. If a layer is hit, the point will contain the original point as translated into that layer's coordinate system. If no layer is hit, the point will be changed to an undefined value.
- Returns:
- this layer if it was the hit layer, a child of this layer if a child of this layer was hit, or null if neither this layer, nor its children were hit.
-
hitTestDefault
LikehitTest(pythagoras.f.Point)
except that it ignores a configuredLayer.HitTester
. This allows one to configure a hit tester which checks custom properties and then falls back on the default hit testing implementation. -
setHitTester
Configures a custom hit tester for this layer. May also be called with null to clear out any custom hit tester.- Returns:
- a reference to this layer for call chaining.
-
absorbHits
Configures a hit tester for this layer which hits this layer any time a hit does not hit a child of this layer. This absorbs all hits that would otherwise propagate up to this layer's parent. Note that this does not do any calculations to determine whether the hit is within the bounds of this layer, as those may or may not be known. All all hits that are checked against this layer are absorbed. -
setBatch
Configures a custom batch (i.e. shader) for use when rendering this layer (and its children). Passing null will cause the default batch to be used. Configuring a batch on a group layer will cause that shader to be used when rendering the group layer's children, unless the child has a custom batch configured itself.- Returns:
- a reference to this layer for call chaining.
-
visit
Visits this layer and its children, in depth first order, withvisitor
. -
debugPrint
Prints a debug representation of this layer and its children.- Parameters:
log
- the output will go to this log (at the debug level).
-
paint
Renders this layer tosurf
, including its children. -
toString
-