Contents

Goals

  • learn how to create shapes in MT4j
  • learn what functionality MT4j shapes provide
  • learn how to change the shape's geometry and appearance
  • learn about bounding shapes and how to use them

Introduction

MT4j provides several classes for common geometric shapes. These geometric shapes are defined by vertices, which are points in 3D space describing the shape's geometry. All shapes in the shapes package extend the AbstractShape class which provides the basic funcitonality for shapes.

Currently, MT4j offers several shape classes:
2D:

  • Line
  • Rectangle
  • Round rectangle
  • Polygon
  • Ellipse

3D:

Shapes provide following functionality:

  • setting a shape's position
  • setting the style and appearance
  • getting the shape's dimensions and center point
  • handling of vertices in a GeometryInfo object
  • calculation of a bounding shape used for picking, dimensions, visibility and centerpoint calculations
  • special OpenGL hardware acceleration (displaylists, vbo)
  • setting up the default multi-touch input processors

Creating and destroying shapes

As shapes extend the MTComponent class the instructions for creating and destroying components in the components tutorial also apply to shapes.
At the creation of shapes we either have to provide the vertices used for the shape or other parameters that allow the calculation of these vertices.

Example:

Vertex[] v = new Vertex[]{
                new Vertex(0,0,0,   255,0,0,255),
                new Vertex(100,0,0, 0,255,0,255),
                new Vertex(50,50,0, 0,0,255,255),
};
MTPolygon p = new MTPolygon(v, mtApplication);
 
           image:TriangleGrad.png

In this example we use the MTPolygon class to specify a triangle shape. The vertices used in the shape are defined by a Vertex array. As we can see, besides the position we can also specify a different color for each vertex. This will create a gradient effect. We also notice that the outline stroke doesent draw the last line. If we want the outline stroke to close the path we have to specify the first vertex one more time at the end of the vertex array.

Example:

MTEllipse ellipse = new MTEllipse(mtApplication, new Vector3D(100,100,0), 60, 40);
 
           image:EllipseDefault.png

This would create an ellipse with the center point at (100,100,0). The shape will calculate all the vertices needed for the ellipse itself.

Changing a shape's geometry

The geometry, and with it the shape itself can be changed by changing the shape's vertices. Therefore, shapes offer the setVertices() and the setGeometryInfo() methods. The setVertices() method takes an array of vertices as an argument which will then define the shape. Internally, the setVertices() method creates a new GeometryInfo object which encapsulates all the information needed to describe the shapes geometry. We can also provide a new GeometryInfo object directly to the shape using the setGeometryInfo() method. For the creation of a geometryInfo object we need to specify an array of vertices as well. Besides the vertices, we can also specify an array of normals used for lightning calculations and an array of indices used for indexed geometry (mostly used at triangle meshes).

Relevant Methods:

Setting and changing a shape's appearance

Every shape has a StyleInfo object with contains and defines most of the shape's appearance such as:

  • fill color
  • outline stroke color
  • stroke weight (width)

We can change these settings individually by using the corresponding method or we can change all settings at once by providing a new StyleInfo object using setStyleInfo().

Colors

When setting colors, we have to specify MTColor objects. MT4j uses the RGBA color model which is an additive color model in which red, green, and blue are added together resulting in the final color. Additionally we can set an alpha value (=transparency). The allowed value range is from 0 to 255 for each component. The default color for shapes is white.

Filling

The interior of a shape can be painted with a solid color using the setFillColor() method of the shape.

Example:

ellipse.setFillColor(new MTColor(0,0,255));
 
           image:EllipseFilled.png

If we dont want the shape to be filled at all, we can invoke the shape's setNoFill() method with "true". Example:

ellipse.setNoFill(true);
 
           image:EllipseNoFill.png

Outline Stroke

Most shapes allow to draw their countour as a stroked outline. The color of the outline can be set using the setStrokeColor() method while the width of the stroke is controlled by the setStrokeWeight() method.

ellipse.setStrokeColor(new MTColor(255,0,255));
ellipse.setStrokeWeight(3);
 
           image:EllipseStrokedFilled.png

We can also omit drawing the outline completely by using the setNoStroke() method.

ellipse.setNoStroke(true);
 
           image:EllipseNoStroke.png

Now, only the filling will be drawn.

Note: If we set both noStroke and noFill to true, the shape will draw nothing at all!

Textures

Shapes also allow to use a texture image as the filling by mapping an image onto the shape. The information of how to map the image onto the shape is contained in the shapes vertices and can be changed on a vertex using the setTextureCoordinateU() and setTextureCoordinateV() methods. MT4j shapes like the MTRectangle, MTRoundRectangle and MTEllipse already contain default texture coordinates so we just have to set the texture using the setTexture() method. General information on texture mapping can be found here on wikipedia.

Example:

PImage p = mtApplication.loadImage(MT4jSettings.getInstance().getDefaultImagesPath() + 
"keyb2.png");
ellipse.setTexture(p);
 
           image:EllipseTextured.png

This shows how to load an image from file and use it as a texture on a MT4j shape. We notice that the fill color setting still influences the texture and tints it blue. If we want to display the texture un-tinted we have to change the fill color to white.

Relevant Methods:

Positioning shapes

All shapes provide methods for positioning them in space by taking their center point as reference. As usual, we have to specify which coordinate space we want the position to be relative to.

Note: The center point is calculated using a bounding shape of the real shape so the result of a positioning might sometimes be slightly different than expected.

Example:

  mtEllipse.setPositionGlobal(new Vector3D(200,250,100));

The ellipse's center will now be at P=(200,250,100) relative to the global space.

Relevant Methods:

Size of shapes

All provided shapes offer methods to measure their width and height. The calculation is done, using the shape's bounding shape. If the shape has no bounding shape, a temporary bounding shape is created. The precision of the calculated dimensions depend on how well the bounding shape fits the real shape. The TransformSpace parameter specifies which coordinate space the dimensions should be relative to.
These methods are primarily useful in 2D applications since we can't really use the terms "width" and "height" in a 3D context where shapes can be rotated freely about all three axis.

Relevant Methods:

Bounding Shapes

Bounding shapes are geometric shapes that fully contain another shape. The geometry of the bounding shape is usually less complex than the geometry of the "real" shape to facilitate and speed up calculations like intersection tests for example.

MT4j allows to create and assign following bounding shapes to shapes:

  • bounding sphere (BoundingSphere)
  • oriented bounding box (OrientedBoundingBox)
  • oriented bounding rectangle (2D on Z=0 plane) (BoundsZPlaneRectangle)
  • planar bounding polygon (2D on Z=0 plane) can be used as an arbitrary 2d shape as the bounding shape (BoundsArbitraryPlanarPolygon)

When assigning bounding shapes we should consider which bounding shape will fit the real shape best. If we know that a shape will only be used on the Z=0 plane in space (usually the case with 2D shapes) for example, we would assign the oriented bounding rectangle to the shape. This can significantly speed up picking and intersection tests. For 3D shapes (=> MTTriangleMesh shapes or 2D shapes that dont lie in the z=0 plane) we can choose between the bounding sphere and bounding box shapes. For all MT4j shapes, a default 3D bounding shape is computed automatically at initialization (usually a oriented bounding box or bounding sphere). So setting a bounding shape is only necessary if the default bounding shape isn't ideal.

Bounding shapes are used in following calculcations:

  • ray-shape intersection test (at picking for example)
  • point in shape test
  • shape center point calculation
  • shape width and height calculation

How and in which calculations the bounding shape is used can be set using the setBoundsPickingBehaviour() method. It accepts one of the three constant values:

  • AbstractShape.BOUNDS_ONLY_CHECK
    -> Uses the shape's bounding shape for all the above calculations
    => faster, less accurate
  • AbstractShape.BOUNDS_DONT_USE
    -> Uses only the shape's real geometry for the calculations
    => slower, often more accurate
  • AbstractShape.BOUNDS_CHECK_THEN_GEOMETRY_CHECK
    -> Uses the shape's bounding shape first, and then tests the geometry (e.g. at picking). (Default mode)
    => compromise between the other two

Relevant Methods:

Retrieved from "https://mt4j.org/mediawiki/index.php/Tutorial:_Geometric_shapes_in_MT4j"
Powered by MediaWiki contact