<commit_before>/**
 * Copyright 2010 The PlayN Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package playn.core;

import pythagoras.f.IPoint;
import pythagoras.f.Point;
import pythagoras.f.Transform;

import playn.core.gl.GLShader;

/**
 * Layer is the base element for all rendering in PlayN
 * <p>
 * Each layer has a transformation matrix {@link #transform()} and several other associated
 * properties which can be manipulated directly (changes take effect automatically on the next
 * rendered frame).
 * <p>
 * The root of the layer hierarchy is the {@link Graphics#rootLayer() rootLayer} . All coordinates
 * in a layer are transformed by the layer's transformation matrix, and each child layer is
 * positioned by the transformation matrix of it's parent.
 * <p>
 * TODO: clipping (?), transform-origin: allow explicit
 * "center, top-left, bottom-right" like CSS transform-origin?
 */
public interface Layer {

  /** Used to customize a layer's hit testing mechanism. */
  interface HitTester {
    /** Returns {@code layer}, or a child of {@code layer} if the supplied coordinate (which is in
     * {@code layer}'s coordinate system) hits {@code layer}, or one of its children. This allows a
     * layer to customize the default hit testing approach, which is to simply check whether the
     * point intersects a layer's bounds. See {@link Layer#hitTest}. */
    Layer hitTest (Layer layer, Point p);
  }

  /**
   * Destroys this layer, removing it from its parent layer. Any resources associated with this
   * layer are freed, and it cannot be reused after being destroyed. Destroying a layer that has
   * children will destroy them as well.
   */
  void destroy();

  /**
   * Whether this layer has been destroyed. If true, the layer can no longer be used.
   */
  boolean destroyed();

  /**
   * Returns the parent that contains this layer, or {@code null}.
   */
  GroupLayer parent();

  /**
   * 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.
   *
   * <p><em>Note:</em> any direct modifications to this matrix <em>except</em> modifications to its
   * translation, will be overwritten if a call is subsequently made to {@link #setScale(float)},
   * {@link #setScale(float,float)}, {@link #setScaleX}, {@link #setScaleY} or {@link #setRotation}.
   * If you intend to manipulate a layer's transform matrix directly, <em>do not</em> call those
   * other methods. Also do not expect {@link #scaleX}, {@link #scaleY}, or {@link #rotation} to
   * reflect the direct changes you've made to the transform matrix. They will not. </p>
   */
  Transform transform();

  /**
   * Returns true if this layer is visible (i.e. it is being rendered).
   */
  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.
   *
   * @return a reference to this layer for call chaining.
   */
  Layer setVisible(boolean visible);

  /**
   * Returns true if this layer reacts to clicks and touches. If a layer is interactive, it will
   * respond to {@link #hitTest}, which forms the basis for the click and touch processing provided
   * by the various {@code addListener} methods.
   */
  boolean interactive();

  /**
   * Configures this layer as reactive to clicks and touches, or not. Note that a layer's
   * interactivity is automatically activated when a listener is added to the layer (or to a child
   * of a {@link GroupLayer}) via {@link #addListener}, etc. Also a {@link GroupLayer} will be made
   * non-interactive automatically if an event is dispatched to it and it discovers that it has no
   * interactive children. Manual management of interactivity is thus generally only useful for
   * "leaf" nodes in the scene graph.
   *
   * @return a reference to this layer for call chaining.
   */
  Layer setInteractive(boolean interactive);

  /**
   * Return the global alpha value for this layer.
   * <p>
   * The global alpha value for a layer controls the opacity of the layer but does not affect the
   * current drawing operation. I.e., when {@link Game#paint(float)} is called and the {@link Layer}
   * is drawn, this alpha value is applied to the alpha channel of the Layer.
   * <p>
   * By default, the alpha for a Layer is 1.0 (not transparent).
   *
   * @return alpha in range [0,1] where 0 is transparent and 1 is opaque
   */
  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 {@link #setTint}.
   *
   * <p> Values outside the range [0,1] will be clamped to the range [0,1]. </p>
   *
   * @param alpha alpha value in range [0,1] where 0 is transparent and 1 is opaque.
   *
   * @return a reference to this layer for call chaining.
   */
  Layer setAlpha(float alpha);

  /** Returns the current tint for this layer, as {@code ARGB}. */
  int tint();

  /**
   * Sets the tint for this layer, as {@code ARGB}.
   *
   * <p> <em>NOTE:</em> this will overwrite any value configured via {@link #setAlpha}. Either
   * include your desired alpha in the high bits of {@code tint} or call {@link #setAlpha} after
   * calling this method. </p>
   *
   * <p> <em>NOTE:</em> 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. </p>
   *
   * <p> The tint for a layer controls the opacity of the layer but does not affect the current
   * drawing operation. I.e., when {@link Game#paint(float)} is called and the {@link Layer} is
   * drawn, this tint is applied when rendering the layer. </p>
   *
   * @return a reference to this layer for call chaining.
   */
  Layer setTint(int tint);

  /**
   * Returns the x-component of the layer's origin.
   */
  float originX();

  /**
   * Returns the y-component of the layer's origin.
   */
  float originY();

  /**
   * Sets the origin of the layer.
   * <p>
   * This sets the origin of the layer's transformation matrix.
   *
   * @param x origin on x axis
   * @param y origin on y axis
   *
   * @return a reference to this layer for call chaining.
   */
  Layer setOrigin(float x, float y);

  /**
   * Sets the depth of this layer. Within a single {@link GroupLayer}, layers are rendered from
   * lowest depth to highest depth.
   */
  float depth();

  /**
   * Updates this layer's depth.
   *
   * @return a reference to this layer for call chaining.
   */
  Layer setDepth(float depth);

  /**
   * Returns this layer's current translation in the x direction.
   */
  float tx();

  /**
   * Returns this layer's current translation in the y direction.
   */
  float ty();

  /**
   * Sets the x translation of this layer.
   *
   * <p><em>Note:</em> all transform changes are deferred until {@link #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. </p><commit_msg>Fixed the Javadoc for Layer's depth() and setDepth() methods.<commit_after>/**
 * Copyright 2010 The PlayN Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package playn.core;

import pythagoras.f.IPoint;
import pythagoras.f.Point;
import pythagoras.f.Transform;

import playn.core.gl.GLShader;

/**
 * Layer is the base element for all rendering in PlayN
 * <p>
 * Each layer has a transformation matrix {@link #transform()} and several other associated
 * properties which can be manipulated directly (changes take effect automatically on the next
 * rendered frame).
 * <p>
 * The root of the layer hierarchy is the {@link Graphics#rootLayer() rootLayer} . All coordinates
 * in a layer are transformed by the layer's transformation matrix, and each child layer is
 * positioned by the transformation matrix of it's parent.
 * <p>
 * TODO: clipping (?), transform-origin: allow explicit
 * "center, top-left, bottom-right" like CSS transform-origin?
 */
public interface Layer {

  /** Used to customize a layer's hit testing mechanism. */
  interface HitTester {
    /** Returns {@code layer}, or a child of {@code layer} if the supplied coordinate (which is in
     * {@code layer}'s coordinate system) hits {@code layer}, or one of its children. This allows a
     * layer to customize the default hit testing approach, which is to simply check whether the
     * point intersects a layer's bounds. See {@link Layer#hitTest}. */
    Layer hitTest (Layer layer, Point p);
  }

  /**
   * Destroys this layer, removing it from its parent layer. Any resources associated with this
   * layer are freed, and it cannot be reused after being destroyed. Destroying a layer that has
   * children will destroy them as well.
   */
  void destroy();

  /**
   * Whether this layer has been destroyed. If true, the layer can no longer be used.
   */
  boolean destroyed();

  /**
   * Returns the parent that contains this layer, or {@code null}.
   */
  GroupLayer parent();

  /**
   * 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.
   *
   * <p><em>Note:</em> any direct modifications to this matrix <em>except</em> modifications to its
   * translation, will be overwritten if a call is subsequently made to {@link #setScale(float)},
   * {@link #setScale(float,float)}, {@link #setScaleX}, {@link #setScaleY} or {@link #setRotation}.
   * If you intend to manipulate a layer's transform matrix directly, <em>do not</em> call those
   * other methods. Also do not expect {@link #scaleX}, {@link #scaleY}, or {@link #rotation} to
   * reflect the direct changes you've made to the transform matrix. They will not. </p>
   */
  Transform transform();

  /**
   * Returns true if this layer is visible (i.e. it is being rendered).
   */
  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.
   *
   * @return a reference to this layer for call chaining.
   */
  Layer setVisible(boolean visible);

  /**
   * Returns true if this layer reacts to clicks and touches. If a layer is interactive, it will
   * respond to {@link #hitTest}, which forms the basis for the click and touch processing provided
   * by the various {@code addListener} methods.
   */
  boolean interactive();

  /**
   * Configures this layer as reactive to clicks and touches, or not. Note that a layer's
   * interactivity is automatically activated when a listener is added to the layer (or to a child
   * of a {@link GroupLayer}) via {@link #addListener}, etc. Also a {@link GroupLayer} will be made
   * non-interactive automatically if an event is dispatched to it and it discovers that it has no
   * interactive children. Manual management of interactivity is thus generally only useful for
   * "leaf" nodes in the scene graph.
   *
   * @return a reference to this layer for call chaining.
   */
  Layer setInteractive(boolean interactive);

  /**
   * Return the global alpha value for this layer.
   * <p>
   * The global alpha value for a layer controls the opacity of the layer but does not affect the
   * current drawing operation. I.e., when {@link Game#paint(float)} is called and the {@link Layer}
   * is drawn, this alpha value is applied to the alpha channel of the Layer.
   * <p>
   * By default, the alpha for a Layer is 1.0 (not transparent).
   *
   * @return alpha in range [0,1] where 0 is transparent and 1 is opaque
   */
  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 {@link #setTint}.
   *
   * <p> Values outside the range [0,1] will be clamped to the range [0,1]. </p>
   *
   * @param alpha alpha value in range [0,1] where 0 is transparent and 1 is opaque.
   *
   * @return a reference to this layer for call chaining.
   */
  Layer setAlpha(float alpha);

  /** Returns the current tint for this layer, as {@code ARGB}. */
  int tint();

  /**
   * Sets the tint for this layer, as {@code ARGB}.
   *
   * <p> <em>NOTE:</em> this will overwrite any value configured via {@link #setAlpha}. Either
   * include your desired alpha in the high bits of {@code tint} or call {@link #setAlpha} after
   * calling this method. </p>
   *
   * <p> <em>NOTE:</em> 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. </p>
   *
   * <p> The tint for a layer controls the opacity of the layer but does not affect the current
   * drawing operation. I.e., when {@link Game#paint(float)} is called and the {@link Layer} is
   * drawn, this tint is applied when rendering the layer. </p>
   *
   * @return a reference to this layer for call chaining.
   */
  Layer setTint(int tint);

  /**
   * Returns the x-component of the layer's origin.
   */
  float originX();

  /**
   * Returns the y-component of the layer's origin.
   */
  float originY();

  /**
   * Sets the origin of the layer.
   * <p>
   * This sets the origin of the layer's transformation matrix.
   *
   * @param x origin on x axis
   * @param y origin on y axis
   *
   * @return a reference to this layer for call chaining.
   */
  Layer setOrigin(float x, float y);

  /**
   * Returns this layer's current depth.
   */
  float depth();

  /**
   * Sets the depth of this layer.
   * <p>
   * Within a single {@link GroupLayer}, layers are rendered from lowest depth to highest depth.
   *
   * @return a reference to this layer for call chaining.
   */
  Layer setDepth(float depth);

  /**
   * Returns this layer's current translation in the x direction.
   */
  float tx();

  /**
   * Returns this layer's current translation in the y direction.
   */
  float ty();

  /**
   * Sets the x translation of this layer.
   *
   * <p><em>Note:</em> all transform changes are deferred until {@link #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. </p>
{'fraction_non_alphanumeric': 0.09214930840649277, 'fraction_numerical': 0.0034105981178551128, 'mean_word_length': 3.1977730646871687, 'pattern_counts': {'":': 0, '<': 64, '<?xml version=': 0, '>': 64, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7532668', 'n_tokens_mistral': 4443, 'n_tokens_neox': 4259, 'n_words': 2183}