LibGDX Tutorial Translation - Part 3 (scene2d package)

This is the third article from the libGDX tutorials translation cycle.
The first article is here.
The second article is here.

scene2d

The scene2d package represents classes for implementing a graph for a two-dimensional scene that can be useful for managing a group of hierarchically related actors (an actor is an entity that can be drawn and that can handle input events - translator notes). This package provides support for handling management, drawing with the ability to rotate and scale the actors in the coordinate system relative to the parent actor. This package also provides a framework for managing the actions of actors through some intervals (tweening). The package scene2d.ui provides actors who can be helpful in building a graphical user interface.

Important classes from the package

')
The Stage class has a “root” group (group) where an application can add its actors. The Stage class has its own camera and its own SpriteBatch wrapper. The viewing area of ​​the camera is set to the screen size. When the Stage class is rendered, SpriteBatch draws the root group. However, the Stage implements the InputProcessor interface and sends input events to the root group.

Class Group is an actor who may contain other actors. The rotation and scaling of the Group has a corresponding effect on its subsidiary actors. The Group class delegates drawing and input events to the corresponding child actors. It turns the input event coordinates so that the children get these coordinates in their own coordinate system.

The Actor class provides basic functionality for representing a scene graph node. It has a position, size, information about the scale, rotation, parent component (origin). Also, an actor can have a name, which allows you to find it by that name and can help with debugging (you can display a hierarchy of actors with their names).

Configuring the Stage class

The Stage class has a viewport. You can set it in the constructor, although it would be a good idea to set this area when the application changes its size. The constructor also accepts a boolean parameter that is called stretch. If this parameter is set to true, the Stage class, when drawing, will stretch (compress) the image to fit the screen, if the screen size does not match the size of the Stage viewport. If this parameter is false, the Stage viewport will be reduced to the screen resolution. If the viewport is configured in the resize () method, the value of this parameter is irrelevant.

The Stage class has a method called act, which takes the time that has passed since the last frame was drawn. Calling this method leads to calling the act method on other actors, which allows actors to perform certain actions at certain intervals. Calling the act method on the Stage class is optional.

private Stage stage; public void create () { stage = new Stage(0, 0, true); } public void resize (int width, int height) { stage.setViewport(width, height, true); } public void render () { Gdx.gl.glClear(GL10.GL_COLOR_BUFFER_BIT); stage.act(Gdx.graphics.getDeltaTime()); stage.draw(); } public void dispose() { stage.dispose(); } 

Actors

Extend the abstract class Actor and implement in it methods for drawing, defining keystrokes and handling controls in the scene graph.

Drawing

When the drawing method for the Stage class is called, it calls the drawing method for the root group. In turn, the root group invokes drawing methods on child actors. To draw an actor, implement the draw () method:

 TextureRegion region; public void draw (SpriteBatch batch, float parentAlpha) { batch.setColor(1, 1, 1, parentAlpha); batch.draw(region, x, y, width, height); } 

SpriteBatch, which receives an actor already configured by the parent actor (root group) to correctly display the actor relative to the bottom left corner of the root group. These are such parameters as the location of the actor, its size, information about scaling, rotation. This makes it very easy to draw an actor in the right place. In the code above, the parameters x, y, width, height are public fields of the class Actor.

If the visible parameter is set to false for a particular actor, the root group will not call its draw () method.

The parentAlpha parameter, which is passed to the draw () method, is the color transparency value of the parent component. Given this parameter, the root group and child actors can be translucent (translucent).

The begin () method of the SpriteBatch class is already called when the draw () method is called on a particular actor. If an actor needs to draw himself in some other way, for example, using the ShapeRenderer class, the SpriteBatch class must complete and restart the packaging of the sprites (the begin () and end () methods must be called). Of course, this will lead to the clearing of the sprite packer buffer, so you need to use this feature carefully (there may be performance losses - note of the translator). You can use the projection matrix and the transformation matrix from the SpriteBatch class:

 private ShapeRenderer renderer; public void draw (SpriteBatch batch, float parentAlpha) { batch.end(); renderer.setProjectionMatrix(batch.getProjectionMatrix()); renderer.setTransformMatrix(batch.getTransformMatrix()); renderer.translate(x, y, 0); renderer.begin(ShapeType.Rectangle); renderer.rect(0, 0, width, height); renderer.end(); batch.begin(); } 

Click definition

When you call the hit () method on the Stage () class, it calls the hit () method on the root group. The root group calls the hit () method on the child actors. The first return value of type Actor will be the return result of the Stage class. (That is, we descend through the hierarchy of actors, and as soon as any actor "thinks" that he was clicked, he returns himself, and the Stage class returns this actor. - comment of the translator). To intercept clicks, implement the hit () method of the actor:

 public Actor hit (float x, float y) { return x > 0 && x < width && y > 0 && y < height ? this : null; } 

The hit () method returns the actor that was clicked on, or null otherwise. Coordinates are taken relative to the coordinate system of the actor. The code above shows a typical implementation when we return an actor if we clicked a point that falls into the rectangle of the actor.

Touch event handling

To handle the control, implement the touchDown (), touchDragged () and touchUp () methods:

 public boolean touchDown (float x, float y, int pointer) { return true; } public void touchDragged (float x, float y, int pointer) { } public void touchUp (float x, float y, int pointer) { } 

When the touchDown () method is called for the Stage class, the touchDown () method is called for the root group. The root group calls the hit () method for the child actors. The touchDown () method is called for the first actor, which is returned by the hit () method. If the touchDown () call for this actor returns false, this means that the actor ignores the event and the process continues for the next actor. If touchDown () returns true, the actor gets the input focus. This means that it calls touchDragged () and touchUp () methods, unless of course it ignores them. When the touchUp () method is called for an actor, which is guaranteed to happen, the actor loses the input focus.

The touchDown () method for the Group class sends touchDown messages to child actors. If this method is redefined, you must call the base method super (). TouchDown (), otherwise the actors will not receive any events about pressing.

There is also one additional method for handling clicks that can be overridden, the touchMoved () method. It can only be called on a desktop PC and it is called when you move the mouse.

Similar to the hit () method, the coordinates that are passed to the control handler methods are given in the actor’s coordinate system.

If the touchable field is set to false for an actor, the Group class will not call methods to handle the control for that actor.

To handle keyboard controls that can only happen on a desktop PC, override the keyDown (), keyUp, and keyTyped () methods. They can only be called when the actor receives keyboard input focus. This focus can be obtained and reset by calling the Stage class keyboardFocus () method.

To handle mouse scrolling, which can only happen on a desktop PC, override the scrolled () method. It will be called only when the actor has a focus for scrolling. This focus is set and reset by the Stage class scrollFocus method.

Addition: the project with an example