Drawing arbitrary shapes with OpenGL points
Written by Lucas on
Part of my Google Summer of Code project involves porting several arrow heads from Glumpy to Vispy. I also want to make a slight change to them: the arrow heads in Glumpy include an arrow body, I want to remove that to make sure you can put an arrow head on every type of line you want.
Making a change like that requires that you understand how those shapes are drawn. And for someone without a background in computer graphics this took some thorough investigation of the code and the techniques used. This article is aimed at people like me: good enough programming skills and linear algebra knowledge, but almost no former experience with OpenGL or computer graphics in general.
Implicit surfaces
The basic principle behind drawing these 2D shapes is called implicit surfaces, and it relies on a arbitrary shape function which for a given point in your image returns the distance to your shape surface or boundary from that given point. This is visualized in fig. 1.
The distances any shape function should return are highlighted in red. To actually be able to draw a shape, we need to distinguish whether a point lies inside the shape or not. We make the arbitrary decision that a negative distance lies inside a shape, and a positive distance means that the point lies outside the shape.
Distance functions for a few basic shapes
The distance functions defined below have one requirement: the center point of the shape has the coordinate (0, 0).
Circle
For a circle these distances are easily calculated:
d(x) = x − r (1)
Where:
x:
Vector to the point in consideration.
r:
The radius of the circle.
If the point lies within the circle, the length of the vector towards that point is smaller than the radius, making the distance automatically negative.
Square
Consider fig. 2.
A square is a nice symmetric figure, so we can take the absolute values of the coordinates, and then we only need to consider the smaller highlighted square (light blue).
The distance to the boundary of the square is then:
$$ d(\textbf{x}) = \text{max}(x_1, x_2)  \frac{s}{2} \qquad(2)$$
Where:
x:
Vector towards the point in consideration
x_{1} and x_{2} are the absolute values of the first and second element of the vector (the x and y coordinates).
s:
The size of the square.
Using the max function we sort of select to which boundary the distance will be calculated. Then we substract the size of the smaller square (highlighted with light blue). The resulting distance is then negative if the point lies within the square, and positive otherwise.
Combining shapes
To make more complex shapes, it is often useful to combine multiple simple shapes. To do this, we introduce some basic operations on the returned distances of a simple shape, based on [1].
Inverse
We made the arbitrary decision to say that the distance is negative when a point lies within the shape. To get the inverse of a shape we simply need to negate each distance value.
∀x, y : ¬S(x, y) = − S(x, y) (3)
Union
The union of two shapes can be retrieved by using the min function on both distance functions.
∀x, y : U(x, y) = min(S1(x, y), S2(x, y)) (4)
Remember that the distance value is negative when the point lies in the shape. The lowest value will win here, so if one of those distances is negative (the point belongs to at least one shape), it will return the negative value. Thus combining both shapes to a single one.
Difference
The difference of two shapes contains all points in S1 excluding the points in S2. This is defined as follows:
∀x, y : D(x, y) = max(S1(x, y), − S2(x, y)) (5)
Consider the example where S1(x, y) = − 2 and S2(x, y) = − 1. In short, the current point (x, y) belongs to both S1 and S2. Using the above function for the difference, the value from S2 gets negated: − S2(x, y) = 1. Due to the max function, this value will win (it's higher than 2), and therefore, it will not be part of the new shape. Which is precisely what we want, because we want all points that are part of S1 but not part of S2.
Intersection
The intersection of two shapes contains all points that are both part of S1 and S2. It is defined as follows:
∀x, y : I(x, y) = max(S1(x, y), S2(x, y)) (6)
A point will be part of the new shape if and only if both distances are negative. If one distance is positive, the max function will return this value, and a positive value means not part of the shape. This results in a shape which includes only points that are both part of S1 and S2.
OpenGL implementation
So how do we translate these principles to some working code? Let us first introduce some basic OpenGL concepts before throwing the shader code at you.
Shaders and drawing modes
I will not go too deep in the basics of OpenGL, but a modern OpenGL pipeline consists of multiple shaders, small programs you can write yourself. At the very minimum you'll need a vertex shader and a fragment shader, which determine where the main "drawing points'' will be positioned and the color of the individual pixels respectively. The pipeline is illustrated in fig. 3.
You can define your own attributes for each vertex, for example the position, colour, or orientation.
OpenGL has several modes for generating the actual primitives. These are illustrated in fig. 4.
For a more in depth OpenGL introduction, I would recommend this tutorial, Anton's OpenGL tutorials, or opengltutorial.org.
General 2D shape shaders
For the 2D shapes we want to draw, we're going to use the points drawing mode. OpenGL allows you to specify the point size, and the fragment shader will be called for each pixel in the point.
Let's check the vertex shader were we position our vertices, and configure the point size.
Vertex shader
Listing 1: The vertex shader code for our 2D shapes
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34  // Uniforms //  uniform float antialias; uniform mat4 ortho; // Attributes //  attribute vec2 position; attribute float size; attribute vec4 color; attribute float rotation; attribute float linewidth; // Varyings //  varying float v_size; varying vec4 v_color; varying vec2 v_rotation; varying float v_antialias; varying float v_linewidth; // Main //  void main (void) { v_size = size; v_linewidth = linewidth; v_antialias = antialias; v_color = color; v_rotation = vec2(cos(rotation), sin(rotation)); gl_Position = ortho * vec4(position, 0, 1); gl_PointSize = M_SQRT2 * size + 2.0 * (linewidth + 1.5*antialias); } 
We first define some uniforms, attributes, and varyings. Uniforms are variables which are the same for each vertex. Attributes are variables defined per vertex, and with varyings we can pass some data to the next steps in the pipeline (for example, the fragment shader).
Each vertex has a position, and this is where our 2D shape will be
drawn. The matrix ortho
is used for the proper projection of the
vertex to your screen. We will not explain this indepth, but if you
want to know more please refer to this
tutorial
on opengltutorial.org.
Our shapes are larger than one pixel, so we need to change
gl_PointSize
. Our shapes also have a size attached to them, but for
the point size we scale this size with $\sqrt{2}$ (ignore the extra
size for antialias en linewidth for now). We do this because our shapes
can be rotated. To fit a rotated square of size x in another square,
we need a bigger square of size $x\sqrt{2}$ (I hope you guys remember
Pythagoras). This is visualized in fig. 5.
Furthermore, we pass along some variables to the next steps in the pipeline (size, line width, antialias, color, rotation). Note we create a direction vector for the rotation from the given rotation in radians.
Fragment shader
Listing 2: The fragment shader code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20  // Varyings //  varying float v_size; varying vec4 v_color; varying vec2 v_rotation; varying float v_antialias; varying float v_linewidth; // Main //  void main() { vec2 P = gl_PointCoord.xy  vec2(0.5,0.5); P = vec2(v_rotation.x*P.x  v_rotation.y*P.y, v_rotation.y*P.x + v_rotation.x*P.y) * v_size; float size = v_size/M_SQRT2; float distance = shape_func(P, size); gl_FragColor = filled(distance, v_linewidth, v_antialias, v_color); } 
Note we have the same varying definitions as in the vertex shader. These
contain values as passed from the vertex shader. Also note the usage of
the built in variable gl_PointCoord
. We specified in the vertex shader
the size of our point in pixels, and for each pixel in this point the
fragment shader gets called. The gl_PointCoord
contains the
coordinates inside the point. The x and y attributes from
gl_PointCoord
range from 0.0 to 1.0, where (0, 0) is the bottom left
corner of the point, and (1, 1) is the top right corner of the point.
There are several operations applied to these coordinates:
 First we substract $\bigl[\begin{smallmatrix}0.5 \\ 0.5 \end{smallmatrix}\bigr]$. This makes sure the origin is in the center of the point, because the distance functions we defined earlier in this article require that.

Next we apply a rotation transformation to the point.
Remember the transformation matrix is:
$$ \begin{bmatrix} \mathrm{cos}(\theta) & \mathrm{sin}(\theta) \\ \mathrm{sin}(\theta) & \mathrm{cos}(\theta) \end{bmatrix}\qquad(7)$$
If you look closely at the code you see that the vector
P
gets multiplied with this matrix. $$ \begin{bmatrix}nx \\ ny\end{bmatrix} = \begin{bmatrix}x \\ y \end{bmatrix} \begin{bmatrix} \mathrm{cos}(\theta) & \mathrm{sin}(\theta) \\ \mathrm{sin}(\theta) & \mathrm{cos}(\theta) \end{bmatrix} = \begin{bmatrix} x \mathrm{cos}(\theta)  y \mathrm{sin}(\theta) \\ x \mathrm{sin}(\theta) + y \mathrm{cos}(\theta) \end{bmatrix} $$ 
We also scale the coordinates with
v_size
.
These transformations are visualized in fig. 6.
The green region in the bottom of fig. 6 is our canvas for drawing our
shape. This is done by shape_func()
, any function that returns the
distance to the boundary of a shape as explained earlier in this
article.
The filled()
function determines the color for the current pixel
determined by the returned distance of shape_func()
. Simply put: if
the returned distance is negative, it returns a color (because it's part
of the shape), otherwise it makes the current pixel transparent. It also
applies some antialiasing techniques which I don't know the details of,
so we will not cover this indepth.
Example: curved arrows
To conclude this article we will look into the distance function of a curved arrow head. A curved arrow head can be constructed using the inverse of the union of three circles. This is visualized in fig. 7, and the accompanying shader code can be seen in lst. 3.
Listing 3: GLSL function to the distance of an arrow
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33  /** * Computes the signed distance to an curved arrow * * Parameters: *  * texcoord : Point to compute distance to * size : size of the arrow head in pixels * * Return: *  * Signed distance to the arrow * */ float arrow_curved(vec2 texcoord, float size) { vec2 start = vec2(size/2, 0.0); vec2 end = +vec2(size/2, 0.0); float height = 0.5; vec2 p1 = start + size*vec2(0, height); vec2 p2 = start + size*vec2(0, +height); vec2 p3 = end; // Head : 3 circles vec2 c1 = circle_from_2_points(p1, p3, 6.0*size).zw; float d1 = length(texcoord  c1)  6*size; vec2 c2 = circle_from_2_points(p2, p3, 6.0*size).xy; float d2 = length(texcoord  c2)  6*size; vec2 c3 = circle_from_2_points(p1, p2, 3.0*size).xy; float d3 = length(texcoord  c3)  3*size; return min(d3, min(d1,d2)); } 
We first define the arrow corner points as p1
, p2
and p3
. We use a
helper function which calculates the center point of a circle through
two points with a given radius r
.
The distance to these circles are then easily calculated, and we use the min function to get the union of these three circles. Our arrow head is exactly the area not covered by these circles (see fig. 7), and therefore we return the inverse of this union.
References
[1] N. P. Rougier, “Antialiased 2D grid, marker, and arrow shaders,” Journal of Computer Graphics Techniques (JCGT), vol. 3, no. 4, pp. 1–52, November 2014 [Online]. Available: http://jcgt.org/published/0003/04/01/
[2] “Modern openGL tutorial with python.” [Online]. Available: http://www.labri.fr/perso/nrougier/teaching/opengl/