com.badlogic.gdx.graphics.glutils
Class ShapeRenderer

java.lang.Object
  com.badlogic.gdx.graphics.glutils.ShapeRenderer

public class ShapeRenderer
extends Object

Renders points, lines, rectangles, filled rectangles and boxes.

This class works with OpenGL ES 1.x and 2.0. In its base configuration a 2D orthographic projection with the origin in the lower left corner is used. Units are given in screen pixels.

To change the projection properties use the setProjectionMatrix(Matrix4) method. Usually the Camera.combined matrix is set via this method. If the screen orientation or resolution changes, the projection matrix might have to be adapted as well.

Shapes are rendered in batches to increase performance. The standard use-pattern looks as follows:

 camera.update();
 shapeRenderer.setProjectionMatrix(camera.combined);
 
 shapeRenderer.begin(ShapeType.Line);
 shapeRenderer.color(1, 1, 0, 1);
 shapeRenderer.line(x, y, x2, y2);
 shapeRenderer.rect(x, y, width, height);
 shapeRenderer.circle(x, y, radius);
 shapeRenderer.end();
 
 shapeRenderer.begin(ShapeType.Filled);
 shapeRenderer.color(0, 1, 0, 1);
 shapeRenderer.rect(x, y, width, height);
 shapeRenderer.circle(x, y, radius);
 shapeRenderer.end();
 
 

The class has a second matrix called the transformation matrix which is used to rotate, scale and translate shapes in a more flexible manner. This mechanism works much like matrix operations in OpenGL ES 1.x. The following example shows how to rotate a rectangle around its center using the z-axis as the rotation axis and placing it's center at (20, 12, 2):

 shapeRenderer.begin(ShapeType.Line);
 shapeRenderer.identity();
 shapeRenderer.translate(20, 12, 2);
 shapeRenderer.rotate(0, 0, 1, 90);
 shapeRenderer.rect(-width / 2, -height / 2, width, height);
 shapeRenderer.end();
 

Matrix operations all use postmultiplication and work just like glTranslate, glScale and glRotate. The last transformation specified will be the first that is applied to a shape (rotate then translate in the above example). The projection and transformation matrices are a state of the ShapeRenderer, just like the color and will be applied to all shapes until they are changed.

Author:

mzechner, stbachmann, Nathan Sweet

Nested Class Summary

static class

ShapeRenderer.ShapeType Shape types to be used with begin(ShapeType).

Constructor Summary

ShapeRenderer()

ShapeRenderer(int maxVertices)

Method Summary

void	arc(float x, float y, float radius, float start, float angle) Calls arc(float, float, float, float, float, int) by estimating the number of segments needed for a smooth arc.
void	arc(float x, float y, float radius, float start, float angle, int segments)
void	begin(ShapeRenderer.ShapeType type) Starts a new batch of shapes.
void	box(float x, float y, float z, float width, float height, float depth) Draws a box.
void	circle(float x, float y, float radius) Calls circle(float, float, float, int) by estimating the number of segments needed for a smooth circle.
void	circle(float x, float y, float radius, int segments)
void	cone(float x, float y, float z, float radius, float height) Calls cone(float, float, float, float, float, int) by estimating the number of segments needed for a smooth circular base.
void	cone(float x, float y, float z, float radius, float height, int segments)
void	curve(float x1, float y1, float cx1, float cy1, float cx2, float cy2, float x2, float y2, int segments)
void	dispose()
void	ellipse(float x, float y, float width, float height) Calls ellipse(float, float, float, float, int) by estimating the number of segments needed for a smooth ellipse.
void	ellipse(float x, float y, float width, float height, int segments)
void	end() Finishes the batch of shapes and ensures they get rendered.
void	flush()
Color	getColor()
ShapeRenderer.ShapeType	getCurrentType() Returns the current ShapeRenderer.ShapeType used
Matrix4	getProjectionMatrix()
ImmediateModeRenderer	getRenderer()
Matrix4	getTransformMatrix()
void	identity() Sets the transformation matrix to identity.
void	line(float x, float y, float x2, float y2) Draws a line in the x/y plane.
void	line(float x, float y, float x2, float y2, Color c1, Color c2) Draws a line in the x/y plane.
void	line(float x, float y, float z, float x2, float y2, float z2) Draws a line.
void	line(float x, float y, float z, float x2, float y2, float z2, Color c1, Color c2) Draws a line.
void	line(Vector2 v0, Vector2 v1) Draws a line.
void	line(Vector3 v0, Vector3 v1) Draws a line.
void	point(float x, float y, float z) Draws a point.
void	polygon(float[] vertices)
void	polygon(float[] vertices, int offset, int count) Draws a polygon in the x/y plane.
void	polyline(float[] vertices)
void	polyline(float[] vertices, int offset, int count) Draws a polyline in the x/y plane.
void	rect(float x, float y, float width, float height) Draws a rectangle in the x/y plane.
void	rect(float x, float y, float width, float height, Color col1, Color col2, Color col3, Color col4) Draws a rectangle in the x/y plane.
void	rect(float x, float y, float width, float height, float originX, float originY, float rotation) Draws a rectangle in the x/y plane.
void	rect(float x, float y, float width, float height, float originX, float originY, float rotation, Color col1, Color col2, Color col3, Color col4) Draws a rectangle in the x/y plane.
void	rotate(float axisX, float axisY, float axisZ, float angle) Multiplies the current transformation matrix by a rotation matrix.
void	scale(float scaleX, float scaleY, float scaleZ) Multiplies the current transformation matrix by a scale matrix.
void	setColor(Color color) Sets the Color to be used by shapes.
void	setColor(float r, float g, float b, float a) Sets the Color to be used by shapes.
void	setProjectionMatrix(Matrix4 matrix) Sets the projection matrix to be used for rendering.
void	setTransformMatrix(Matrix4 matrix)
void	translate(float x, float y, float z) Multiplies the current transformation matrix by a translation matrix.
void	triangle(float x1, float y1, float x2, float y2, float x3, float y3) Draws a triangle in x/y plane.
void	triangle(float x1, float y1, float x2, float y2, float x3, float y3, Color col1, Color col2, Color col3) Draws a triangle in x/y plane with coloured corners.
void	x(float x, float y, float radius) Draws two crossed lines.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ShapeRenderer

public ShapeRenderer()

ShapeRenderer

public ShapeRenderer(int maxVertices)

Method Detail

setColor

public void setColor(Color color)

Sets the Color to be used by shapes.

setColor

public void setColor(float r,
                     float g,
                     float b,
                     float a)

Sets the Color to be used by shapes.

getColor

public Color getColor()

setProjectionMatrix

public void setProjectionMatrix(Matrix4 matrix)

Sets the projection matrix to be used for rendering. Usually this will be set to Camera.combined.

Parameters:

matrix -

getProjectionMatrix

public Matrix4 getProjectionMatrix()

setTransformMatrix

public void setTransformMatrix(Matrix4 matrix)

getTransformMatrix

public Matrix4 getTransformMatrix()

identity

public void identity()

Sets the transformation matrix to identity.

translate

public void translate(float x,
                      float y,
                      float z)

Multiplies the current transformation matrix by a translation matrix.

rotate

public void rotate(float axisX,
                   float axisY,
                   float axisZ,
                   float angle)

Multiplies the current transformation matrix by a rotation matrix.

Parameters:

angle - angle in degrees

scale

public void scale(float scaleX,
                  float scaleY,
                  float scaleZ)

Multiplies the current transformation matrix by a scale matrix.

begin

public void begin(ShapeRenderer.ShapeType type)

Starts a new batch of shapes. All shapes within the batch have to have the type specified. E.g. if ShapeRenderer.ShapeType.Point is specified, only call #point(). The call to this method must be paired with a call to end(). In case OpenGL ES 1.x is used, the projection and modelview matrix will be modified.

Parameters:

type - the ShapeRenderer.ShapeType.

point

public void point(float x,
                  float y,
                  float z)

Draws a point. The ShapeRenderer.ShapeType passed to begin has to be ShapeRenderer.ShapeType.Point.

Parameters:

x -

y -

z -

line

public final void line(float x,
                       float y,
                       float z,
                       float x2,
                       float y2,
                       float z2)

Draws a line. The ShapeRenderer.ShapeType passed to begin has to be ShapeRenderer.ShapeType.Line.

line

public final void line(Vector3 v0,
                       Vector3 v1)

Draws a line. The ShapeRenderer.ShapeType passed to begin has to be ShapeRenderer.ShapeType.Line. Lazy method that "just" calls the "other" method and unpacks the Vector3 for you

line

public final void line(float x,
                       float y,
                       float x2,
                       float y2)

Draws a line in the x/y plane. The ShapeRenderer.ShapeType passed to begin has to be ShapeRenderer.ShapeType.Line.

line

public final void line(Vector2 v0,
                       Vector2 v1)

Draws a line. The ShapeRenderer.ShapeType passed to begin has to be ShapeRenderer.ShapeType.Line. Lazy method that "just" calls the "other" method and unpacks the Vector2 for you

line

public final void line(float x,
                       float y,
                       float x2,
                       float y2,
                       Color c1,
                       Color c2)

Draws a line in the x/y plane. The ShapeRenderer.ShapeType passed to begin has to be ShapeRenderer.ShapeType.Line. The line is drawn with 2 colors interpolated between start & end point.

Parameters:

c1 - Color at start of the line

c2 - Color at end of the line

line

public void line(float x,
                 float y,
                 float z,
                 float x2,
                 float y2,
                 float z2,
                 Color c1,
                 Color c2)

Draws a line. The ShapeRenderer.ShapeType passed to begin has to be ShapeRenderer.ShapeType.Line. The line is drawn with 2 colors interpolated between start & end point.

Parameters:

c1 - Color at start of the line

c2 - Color at end of the line

curve

public void curve(float x1,
                  float y1,
                  float cx1,
                  float cy1,
                  float cx2,
                  float cy2,
                  float x2,
                  float y2,
                  int segments)

triangle

public void triangle(float x1,
                     float y1,
                     float x2,
                     float y2,
                     float x3,
                     float y3)

Draws a triangle in x/y plane. The ShapeRenderer.ShapeType passed to begin has to be ShapeRenderer.ShapeType.Filled or ShapeRenderer.ShapeType.Line.

Parameters:

x1 - x of first point

y1 - y of first point

x2 - x of second point

y2 - y of second point

x3 - x of third point

y3 - y of third point

triangle

public void triangle(float x1,
                     float y1,
                     float x2,
                     float y2,
                     float x3,
                     float y3,
                     Color col1,
                     Color col2,
                     Color col3)

Draws a triangle in x/y plane with coloured corners. The ShapeRenderer.ShapeType passed to begin has to be ShapeRenderer.ShapeType.Filled or ShapeRenderer.ShapeType.Line.

Parameters:

x1 - x of first point

y1 - y of first point

x2 - x of second point

y2 - y of second point

x3 - x of third point

y3 - y of third point

col1 - color of the point defined by x1 and y1

col2 - color of the point defined by x2 and y2

col3 - color of the point defined by x3 and y3

rect

public void rect(float x,
                 float y,
                 float width,
                 float height)

Draws a rectangle in the x/y plane. The x and y coordinate specify the bottom left corner of the rectangle. The ShapeRenderer.ShapeType passed to begin has to be ShapeRenderer.ShapeType.Filled or ShapeRenderer.ShapeType.Line.

rect

public void rect(float x,
                 float y,
                 float width,
                 float height,
                 Color col1,
                 Color col2,
                 Color col3,
                 Color col4)

Draws a rectangle in the x/y plane. The x and y coordinate specify the bottom left corner of the rectangle. The ShapeRenderer.ShapeType passed to begin has to be ShapeRenderer.ShapeType.Filled or ShapeRenderer.ShapeType.Line.

Parameters:

col1 - The color at (x, y)

col2 - The color at (x + width, y)

col3 - The color at (x + width, y + height)

col4 - The color at (x, y + height)

rect

public void rect(float x,
                 float y,
                 float width,
                 float height,
                 float originX,
                 float originY,
                 float rotation)

Draws a rectangle in the x/y plane. The x and y coordinate specify the bottom left corner of the rectangle. The originX and originY specify the point about which to rotate the rectangle. The rotation is in degrees. The ShapeRenderer.ShapeType passed to begin has to be ShapeRenderer.ShapeType.Filled or ShapeRenderer.ShapeType.Line.

rect

public void rect(float x,
                 float y,
                 float width,
                 float height,
                 float originX,
                 float originY,
                 float rotation,
                 Color col1,
                 Color col2,
                 Color col3,
                 Color col4)

Draws a rectangle in the x/y plane. The x and y coordinate specify the bottom left corner of the rectangle. The originX and originY specify the point about which to rotate the rectangle. The rotation is in degrees. The ShapeRenderer.ShapeType passed to begin has to be ShapeRenderer.ShapeType.Filled or ShapeRenderer.ShapeType.Line.

Parameters:

col1 - The color at (x, y)

col2 - The color at (x + width, y)

col3 - The color at (x + width, y + height)

col4 - The color at (x, y + height)

box

public void box(float x,
                float y,
                float z,
                float width,
                float height,
                float depth)

Draws a box. The x, y and z coordinate specify the bottom left front corner of the rectangle. The ShapeRenderer.ShapeType passed to begin has to be ShapeRenderer.ShapeType.Line.

x

public void x(float x,
              float y,
              float radius)

Draws two crossed lines.

arc

public void arc(float x,
                float y,
                float radius,
                float start,
                float angle)

Calls arc(float, float, float, float, float, int) by estimating the number of segments needed for a smooth arc.

arc

public void arc(float x,
                float y,
                float radius,
                float start,
                float angle,
                int segments)

circle

public void circle(float x,
                   float y,
                   float radius)

Calls circle(float, float, float, int) by estimating the number of segments needed for a smooth circle.

circle

public void circle(float x,
                   float y,
                   float radius,
                   int segments)

ellipse

public void ellipse(float x,
                    float y,
                    float width,
                    float height)

Calls ellipse(float, float, float, float, int) by estimating the number of segments needed for a smooth ellipse.

ellipse

public void ellipse(float x,
                    float y,
                    float width,
                    float height,
                    int segments)

cone

public void cone(float x,
                 float y,
                 float z,
                 float radius,
                 float height)

Calls cone(float, float, float, float, float, int) by estimating the number of segments needed for a smooth circular base.

cone

public void cone(float x,
                 float y,
                 float z,
                 float radius,
                 float height,
                 int segments)

polygon

public void polygon(float[] vertices)

See Also:

polygon(float[], int, int)

polygon

public void polygon(float[] vertices,
                    int offset,
                    int count)

Draws a polygon in the x/y plane. The vertices must contain at least 3 points (6 floats x,y). The ShapeRenderer.ShapeType passed to begin has to be ShapeRenderer.ShapeType.Line.

Parameters:

vertices -

polyline

public void polyline(float[] vertices)

See Also:

polyline(float[], int, int)

polyline

public void polyline(float[] vertices,
                     int offset,
                     int count)

Draws a polyline in the x/y plane. The vertices must contain at least 2 points (4 floats x,y). The ShapeRenderer.ShapeType passed to begin has to be ShapeRenderer.ShapeType.Line.

Parameters:

vertices -

end

public void end()

Finishes the batch of shapes and ensures they get rendered.

flush

public void flush()

getCurrentType

public ShapeRenderer.ShapeType getCurrentType()

Returns the current ShapeRenderer.ShapeType used

getRenderer

public ImmediateModeRenderer getRenderer()

dispose

public void dispose()