Package playn.scene

Class Layer

java.lang.Object
playn.scene.Layer
All Implemented Interfaces:
AutoCloseable, Closeable
Direct Known Subclasses:
ClippedLayer, ImageLayer
public abstract class Layer extends Object implements Closeable
A layer is a node in the scene graph. It has a transformation matrix and other properties which can be manipulated directly and which "take effect" the next time the layer is 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".

  • Field Details

  • Constructor Details

  • Method Details

    • name

      public String 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. See setName(java.lang.String).

    • setName

      public Layer setName(String name)
      Sets the name of this layer. See name.
      Returns:
      a reference to this layer for call chaining.

    • parent

      public GroupLayer parent()
      Returns the layer that contains this layer, or null.

    • events

      public Signal<Object> events()
      Returns a signal via which events may be dispatched "on" this layer. The Dispatcher 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, any GroupLayer which has one or more interactive children is also marked as interactive. This allows Dispatchers to be more efficient in their dispatching of UI events.

    • hasEventListeners

      public boolean hasEventListeners()
      Returns true if events has at least one listener. Use this instead of calling Reactor.hasConnections() on events because events 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 to hitTest(pythagoras.f.Point), which forms the basis for the click and touch processing provided by the Dispatchers.

    • setInteractive

      public Layer setInteractive(boolean interactive)
      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 its events 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

      public 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.
      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

      public void onAdded(SignalView.Listener<? super Layer> action)
      Connects action to state such that it is triggered when this layer is added to a rooted scene graph.

    • onRemoved

      public void onRemoved(SignalView.Listener<? super Layer> action)
      Connects action to state such that it is triggered when this layer is removed from a rooted scene graph.

    • onDisposed

      public void onDisposed(SignalView.Listener<? super Layer> action)
      Connects action to state 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 interface AutoCloseable
      Specified by:
      close in interface Closeable

    • transform

      public AffineTransform 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) or setRotation(float). If you intend to manipulate a layer's transform matrix directly, do not call those other methods. Also do not expect scaleX, scaleY, or rotation 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 the Layer 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

      public Layer setAlpha(float alpha)
      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 see setTint(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, as ARGB.

    • setTint

      public Layer setTint(int tint)
      Sets the tint for this layer, as ARGB.

      NOTE: this will overwrite any value configured via setAlpha(float). Either include your desired alpha in the high bits of tint or call setAlpha(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 the Layer 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

      public Point origin(Point into)
      Writes this layer's origin into into.
      Returns:
      into for easy call chaining.

    • origin

      public Vector origin(Vector into)
      Writes this layer's origin into into.
      Returns:
      into for easy call chaining.

    • setOrigin

      public Layer setOrigin(float x, float y)
      Sets the origin of the layer to a fixed position. This automatically sets the layer's logical origin to Layer.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

      public Layer setOrigin(Layer.Origin origin)
      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

      public Layer setDepth(float depth)
      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

      public Point translation(Point into)
      Writes this layer's translation into into.
      Returns:
      into for easy call chaining.

    • translation

      public Vector translation(Vector into)
      Writes this layer's translation into into.
      Returns:
      into for easy call chaining.

    • setTx

      public Layer setTx(float x)
      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

      public Layer setTy(float y)
      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

      public Layer setTranslation(float x, float y)
      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

      public Layer setTranslation(XY trans)
      A variant of setTranslation(float,float) that takes an XY.

    • 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) or setScale(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 the transform 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) or setScale(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 the transform that scale will not be returned by this method.

    • scale

      public Vector scale(Vector into)
      Writes this layer's scale into into.
      Returns:
      into for easy call chaining.

    • setScale

      public Layer setScale(float scale)
      Sets the current x and y scale of this layer to scale.. Note that a scale of 1 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

      public Layer setScaleX(float sx)
      Sets the current x scale of this layer. Note that a scale of 1 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

      public Layer setScaleY(float sy)
      Sets the current y scale of this layer. Note that a scale of 1 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

      public Layer setScale(float sx, float sy)
      Sets the current x and y scale of this layer. Note that a scale of 1 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 the transform that rotation will not be returned by this method.

    • setRotation

      public Layer setRotation(float angle)
      Sets the current rotation of this layer, in radians. The rotation is done around the currently set origin, See setOrigin(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

      public Layer hitTest(Point p)
      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

      public Layer hitTestDefault(Point p)
      Like hitTest(pythagoras.f.Point) except that it ignores a configured Layer.HitTester. This allows one to configure a hit tester which checks custom properties and then falls back on the default hit testing implementation.

    • setHitTester

      public Layer setHitTester(Layer.HitTester tester)
      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

      public Layer 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

      public Layer setBatch(QuadBatch batch)
      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

      public void visit(Layer.Visitor visitor)
      Visits this layer and its children, in depth first order, with visitor.

    • debugPrint

      public void debugPrint(Log log)
      Prints a debug representation of this layer and its children.
      Parameters:
      log - the output will go to this log (at the debug level).

    • paint

      public final void paint(Surface surf)
      Renders this layer to surf, including its children.

    • toString

      public String toString()
      Overrides:
      toString in class Object