libgdx API

com.badlogic.gdx.graphics.glutils
Class ShapeRenderer

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

public class ShapeRenderer
extends java.lang.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.line(x3, y3, x4, y4);
 shapeRenderer.end();
 
 shapeRenderer.begin(ShapeType.Box);
 shapeRenderer.color(0, 1, 0, 1);
 shapeRenderer.box(x, y, z, width, height, depth);
 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.Rectangle);
 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

Nested Class Summary
static class ShapeRenderer.ShapeType
          Shape types to be used with begin(ShapeType).
 
Constructor Summary
ShapeRenderer()
           
ShapeRenderer(int maxVertices)
           
 
Method Summary
 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)
           
 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)
          Calls curve(float, float, float, float, float, float, float, float, int) by estimating the number of segments needed for a smooth curve.
 void curve(float x1, float y1, float cx1, float cy1, float cx2, float cy2, float x2, float y2, int segments)
          Draws a curve in the x/y plane.
 void dispose()
           
 void end()
          Finishes the batch of shapes and ensures they get rendered.
 void filledCircle(float x, float y, float radius)
          Calls filledCircle(float, float, float, int) by estimating the number of segments needed for a smooth circle.
 void filledCircle(float x, float y, float radius, int segments)
           
 void filledCone(float x, float y, float z, float radius, float height)
          Calls filledCone(float, float, float, float, float, int) by estimating the number of segments needed for a smooth circular base.
 void filledCone(float x, float y, float z, float radius, float height, int segments)
           
 void filledRect(float x, float y, float width, float height)
          Draws a filled rectangle in the x/y plane.
 void filledRect(float x, float y, float width, float height, Color c1, Color c2, Color c3, Color c4)
          Draws a filled rectangle in the x/y plane.
 void filledTriangle(float x1, float y1, float x2, float y2, float x3, float y3)
           
 void flush()
           
 ShapeRenderer.ShapeType getCurrentType()
          Returns the current ShapeRenderer.ShapeType used
 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 z, float x2, float y2, float z2)
          Draws a line.
 void point(float x, float y, float z)
          Draws a point.
 void rect(float x, float y, float width, float height)
          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)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, 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.

Parameters:
color -

setColor

public void setColor(float r,
                     float g,
                     float b,
                     float a)
Sets the Color to be used by shapes.

Parameters:
r -
g -
b -
a -

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 -

setTransformMatrix

public void setTransformMatrix(Matrix4 matrix)

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.

Parameters:
x -
y -
z -

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
axisX -
axisY -
axisZ -

scale

public void scale(float scaleX,
                  float scaleY,
                  float scaleZ)
Multiplies the current transformation matrix by a scale matrix.

Parameters:
scaleX -
scaleY -
scaleZ -

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

Parameters:
x -
y -
z -
x2 -
y2 -
z2 -

line

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

Parameters:
x -
y -
x2 -
y2 -

curve

public void curve(float x1,
                  float y1,
                  float cx1,
                  float cy1,
                  float cx2,
                  float cy2,
                  float x2,
                  float y2)
Calls curve(float, float, float, float, float, float, float, float, int) by estimating the number of segments needed for a smooth curve.


curve

public void curve(float x1,
                  float y1,
                  float cx1,
                  float cy1,
                  float cx2,
                  float cy2,
                  float x2,
                  float y2,
                  int segments)
Draws a curve in the x/y plane. The ShapeRenderer.ShapeType passed to begin has to be ShapeRenderer.ShapeType.Curve.


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

Parameters:
x -
y -
width -
height -

filledRect

public void filledRect(float x,
                       float y,
                       float width,
                       float height)
Draws a filled 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.FilledRectangle.

Parameters:
x -
y -
width -
height -

filledRect

public void filledRect(float x,
                       float y,
                       float width,
                       float height,
                       Color c1,
                       Color c2,
                       Color c3,
                       Color c4)
Draws a filled 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.FilledRectangle. The 4 color parameters specify the color for the bottom left, bottom right, top right and top left corner of the rectangle, allowing you to create gradients.

Parameters:
x -
y -
width -
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.Box.

Parameters:
x -
y -
width -
height -

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)

filledCircle

public void filledCircle(float x,
                         float y,
                         float radius)
Calls filledCircle(float, float, float, int) by estimating the number of segments needed for a smooth circle.


filledCircle

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

triangle

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

filledTriangle

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

cone

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

cone

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

filledCone

public void filledCone(float x,
                       float y,
                       float z,
                       float radius,
                       float height)
Calls filledCone(float, float, float, float, float, int) by estimating the number of segments needed for a smooth circular base.


filledCone

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

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


dispose

public void dispose()

libgdx API

Copyright 2010 Mario Zechner (contact@badlogicgames.com), Nathan Sweet (admin@esotericsoftware.com)