VertexArrays

A vertex array is exactly what the name suggest - an array of vertices. A vertex, generally speaking, is a representation of a point and its properties.

Vertices

In JSFML, a Vertex describes a point by its position, color and texture coordinates. Using this information, a set of multiple vertices can describe objects like sprites, shapes, a shape's outline.

In other words, sprites, shapes etc. are merely a subset of what is possible using vertex arrays. They can be used to construct arbitrary polygonal shapes by combining points or triangles after certain rules ( primitive types, see below).

Position

The position of a vertex simply describes where the vertex is located. Generally, this is an absolute position in the world, but it is often used as a position relative to the object's origin (0, 0). This practice makes it easier to make vertex arrays transformable and is therefore recommended for most cases.

Color

A vertex is always drawn with a certain color mask. This can be used for shapes filled with a certain color like the Shape class, or for two very useful effects:

• If a texture is used, the vertex color will be used as a color mask for the texture's color data. For instance, tf the texture's pixel is white, but the vertex color is blue, the pixel will become blue. This is used to realize the sprite's setColor method.
• If two connected vertices (e.g. in the same triangle) have a different color, OpenGL will draw a gradient from one vertex to the other. This effect will be used in the "Gradient" example below.

Texture coordinates

Using texture coordinates for a vertex, you can be determine how a texture will be drawn on the object. Each vertex can be given a position of the texture. If two vertices are connected and a texture is applied, the texture will be spanned between them according to those texture coordinates. This is used by the sprite to display a texture, and also to realize the setTextureRect method.

How texture coordinates work is definitely hard to imagine given a generic text like this. The "Custom Sprite" example on the next tutorial page, Drawables and RenderStates, will show how it works in practice.

VertexArrays

The VertexArray class is a specialized ArrayList (ie all the standard list operations are available for it) that contains vertices and has a PrimitiveType.

It is also a Drawable and can therefore be drawn directly by a RenderTarget. Note, however, that a vertex array is not transformable. The next tutorial chapter, Drawables and RenderStates, will go into the details of achieving that.

Primitive Types

The primitive type of a vertex array, which can be determined using the [setPrimitiveType](http://jsfml.org/javadoc/org/jsfml/graphics/VertexArray.html#setPrimitiveType(org.jsfml.graphics.PrimitiveType\)) method, can be seen as a "rule" that determines how the vertices are put together to form a shape. The Javadoc of the enumeration contains brief descriptions on how the single primitive types work, but a good feeling for what type should be used for what type of shape comes from experimentation and experience. For instance, a Sprite is nothing but a single quad, while the outline of a Shape is internally realized using a triangle strip.

Gradient Example

There are many possibilities for which vertex arrays can be used. The following code sample will realize a simple vertical gradient background from yellow to red.

// ... (create window)

//Create the vertex array
VertexArray gradient = new VertexArray();

//Our gradient will be a rectangular shape - a quad - so we will use the primitive type QUADS
gradient.setPrimitiveType(PrimitiveType.QUADS);

//Create the vertices in counter-clockwise order (standard), beginning with the top left corner of the screen
//The vertices at the top edge of the screen should be yellow
gradient.add(new Vertex(new Vector2f(0, 0), Color.YELLOW));

//Create the bottom left vertex
//The vertices at the bottom edge of the screen should be red
gradient.add(new Vertex(new Vector2f(0, window.getSize().y), Color.RED));

//Create the bottom right vertex (red)
gradient.add(new Vertex(new Vector2f(window.getSize().x, window.getSize().y), Color.RED));

//Create the top right vertex (yellow)
gradient.add(new Vertex(new Vector2f(window.getSize().x, 0), Color.YELLOW));

//Main loop
while(window.isOpen()) {
    window.clear();
    window.draw(gradient);
    window.display();

    // ...
}