# GraphicC – The triangle’s the thing

Pixels, lines, and squares, oh my! And, finally, we come to triangles.  The demo code is thus:

```#include "test_common.h"

void test_writebitmap()
{
size_t width = 480;
size_t height = 480;
pb_rgba pb;
pb_rgba_init(&pb, width, height);

// Draw some triangles
size_t midx = (size_t)(width / 2);
size_t midy = (size_t)(height / 2);

raster_rgba_triangle_fill(&pb, 0, 0, width-1, 0, midx, midy, pRed);
raster_rgba_triangle_fill(&pb, 0, 0, midx, midy, 0, height-1, pGreen);
raster_rgba_triangle_fill(&pb, width-1, 0, midx, midy, width-1, height - 1, pBlue);
raster_rgba_triangle_fill(&pb, midx, midy, 0, height-1, width - 1, height - 1, pDarkGray);

// Now we have a simple image, so write it to a file
int err = write_PPM("test_triangle.ppm", &pb);
}

int main(int argc, char **argv)
{
test_writebitmap();

return 0;
}
```

Why triangles? Well, beyond pixels, and lines, they are one of the most useful drawing primitives. When it finally comes to rendering in 3D for example, it will all be about triangles. Graphics hardware over the years has been optimized to render triangles as well, so it is beneficial to focus more attention to this primitive than to any other. You might think polygons are very useful, but, all polygons can be broken down into triangles, and we’re back where we started.

Here’s the triangle drawing routine:

```#define swap16(a, b) { int16_t t = a; a = b; b = t; }

typedef struct _point2d
{
int x;
int y;
} point2d;

int FindTopmostPolyVertex(const point2d *poly, const size_t nelems)
{
int ymin = INT32_MAX;
int vmin = 0;

size_t idx = 0;
while (idx < nelems) {
if (poly[idx].y < ymin) {
ymin = poly[idx].y;
vmin = idx;
}
idx++;
}

return vmin;
}

void RotateVertices(point2d *res, point2d *poly, const size_t nelems, const int starting)
{
size_t offset = starting;
size_t idx = 0;
while (idx < nelems) {
res[idx].x = poly[offset].x;
res[idx].y = poly[offset].y;
offset++;

if (offset > nelems-1) {
offset = 0;
}

idx++;
}
}

void sortTriangle(point2d *sorted, const int x1, const int y1, const int x2, const int y2, const int x3, const int y3)
{
point2d verts = { { x1, y1 }, { x2, y2 }, { x3, y3 } };

int topmost = FindTopmostPolyVertex(verts, 3);
RotateVertices(sorted, verts, 3, topmost);
}

void raster_rgba_triangle_fill(pb_rgba *pb,
const unsigned int x1, const unsigned int  y1,
const unsigned int  x2, const unsigned int  y2,
const unsigned int  x3, const unsigned int  y3,
int color)
{
int a, b, y, last;

// sort vertices, such that 0 == y with lowest number (top)
point2d sorted;
sortTriangle(sorted, x1, y1, x2, y2, x3, y3);

// Handle the case where points are colinear (all on same line)
if (sorted.y == sorted.y) {
a = b = sorted.x;

if (sorted.x < a)
a = sorted.x;
else if (sorted.x > b)
b = sorted.x;

if (sorted.x < a)
a = sorted.x;
else if (sorted.x > b)
b = sorted.x;

raster_rgba_hline(pb, a, sorted.y, b - a + 1, color);
return;
}

int16_t
dx01 = sorted.x - sorted.x,
dy01 = sorted.y - sorted.y,
dx02 = sorted.x - sorted.x,
dy02 = sorted.y - sorted.y,
dx12 = sorted.x - sorted.x,
dy12 = sorted.y - sorted.y;

int32_t sa = 0, sb = 0;

// For upper part of triangle, find scanline crossings for segments
// 0-1 and 0-2. If y1=y2 (flat-bottomed triangle), the scanline y1
// is included here (and second loop will be skipped, avoiding a /0
// error there), otherwise scanline y1 is skipped here and handled
// in the second loop...which also avoids a /0 error here if y0=y1
// (flat-topped triangle).
if (sorted.y == sorted.y)
last = sorted.y; // Include y1 scanline
else
last = sorted.y - 1; // Skip it

for (y = sorted.y; y <= last; y++)
{
a = sorted.x + sa / dy01;
b = sorted.x + sb / dy02;
sa += dx01;
sb += dx02;
/* longhand:
a = x0 + (x1 - x0) * (y - y0) / (y1 - y0);
b = x0 + (x2 - x0) * (y - y0) / (y2 - y0);
*/

if (a > b) swap16(a, b);
raster_rgba_hline(pb, a, y, b - a + 1, color);
}

// For lower part of triangle, find scanline crossings for segments
// 0-2 and 1-2. This loop is skipped if y1=y2.
sa = dx12 * (y - sorted.y);
sb = dx02 * (y - sorted.y);
for (; y <= sorted.y; y++)
{
a = sorted.x + sa / dy12;
b = sorted.x + sb / dy02;
sa += dx12;
sb += dx02;
/* longhand:
a = x1 + (x2 - x1) * (y - y1) / (y2 - y1);
b = x0 + (x2 - x0) * (y - y0) / (y2 - y0);
*/
if (a > b)
swap16(a, b);

raster_rgba_hline(pb, a, y, b - a + 1, color);
}
}
```

This seems like a lot of work to simply draw a triangle! There are lots of routines for doing this. This particular implementation borrows from a couple of different techniques. The basic idea is to first sort the vertices in scaline order, top to bottom. That is, we want to known which vertex to start from because we’re going to follow an edge down the framebuffer, drawing lines between edges as we go. In a regular triangle, without a flat top or bottom, there will be a switch between driving edges as we encounter the third point somewhere down the scan lines.

At the end, the ‘raster_rgba_hline’ function is called to actually draw a single line. If we wanted to do blending, we’d change this line. If we wanted to use a color per vertex, it would ultimately be dealt with here. All possible. Not necessary for the basic routine. With some refactoring, this could be made more general purpose, and different rendering modes could be included.

This is the only case where I use a data structure, to store the sorted points. Most of the time I just pass parameters and pointers to parameters around.

This is also a good time to mention API conventions. One of the constraints from the beginning is the need to stick with basic C constructs, and not get too fancy. In some cases this is at the expense of readability, but in general things just work out ok, as it’s simple to get used to. So, let’s look at the API here:

```void raster_rgba_triangle_fill(pb_rgba *pb,
const unsigned int x1, const unsigned int  y1,
const unsigned int  x2, const unsigned int  y2,
const unsigned int  x3, const unsigned int  y3,
int color)
```

That’s a total of 8 parameters. If I were going for absolute speed, and I knew the platform I was running on, I might try to limit the parameters to 4, to help ensure they get passed in registers, rather than requiring the use of a stack. But, that’s an optimization that’s iffy at best, so I don’t bother. And why not use some data structures? Clearly x1, y1 is a 2D point, so why not use a ‘point’ data structure. Surely where the data comes from is structured as well. In some cases it is, and in others it is not. I figure that in the cases where the data did come from a structure, it’s fairly easy for the caller to do the dereferencing and pass in the values directly. In the cases where the data did not come from a point structure, it’s a tax to pay to stuff the data into a point structure, simply to have it pass in to a function, which may not need it in that form. So, in general, all the parameters are passed in a ‘denormalized’ form. With small numbers of easy to remember parameters, I think this is fine.

Also, I did decide that it was useful to use ‘const’ in most cases where that is applicable.  This gives the compiler some hints as to how best deal with the parameters, and allows you to specify constants inline for test cases, without compiler complaints.

There is a decided lack of error handling in most of these low level APIs.  You might think that triangle drawing would be an exception.  Shouldn’t I do some basic clipping to the framebuffer?  The answer is no, not at this level.  At a higher level, we might be drawing something larger, where a triangle is but a small part.  At that higher level we’ll know about our framebuffer, or other constraints that might cause clipping of a triangle.  At that level, we can perform the clipping, and send down new sets of triangles to be rendered by this very low level triangle drawing routine.

Of course, this routine could be made even more raw and optimized by breaking out the vertex sorting from the edge following part.  If the triangle vertices don’t change, there’s no need to sort them every time they are drawn, so making the assumption that the vertices are already in framebuffer height order can dramatically simplify the drawing portion.  Then, the consumer can call the sorting routines when they need to, and pass in the sorted vertex values.

And thus APIs evolve.  I’ll wait a little longer before making such changes as I might think of other things that I want to improve along the way.

There you have it then.  From pixels to triangles, the basic framebuffer drawing routines are now complete.  What more could be needed at this level?  Well, dealing with some curvy stuff, like ellipses and rounded rectangles might be nice, all depends on what use cases are more interesting first, drawing pies and graphs, or doing some UI stuff.  The first thing I want to do is display some data related to network traffic events, so I think I’ll focus on a little bit of text rendering first, and leave the ellipse and rounded rects for later.

So, next time around, doing simple bitmap text.