polygon3d(3)

💖 polygon3d — bestie edition 💖

ok so you wanna know about polygon3d and polygon3d_f? say less. this is from the Allegro game programming library manual, section 3 (library functions, the fun ones). let's get into it 🎀

---

✨ NAME ✨

polygon3d, polygon3d_f — draws a 3d polygon onto the specified bitmap. it's giving Allegro game programming library, fr fr.

---

✨ SYNOPSIS ✨

#include <allegro.h>

void polygon3d(BITMAP *bmp, int type, BITMAP *texture, int vc, V3D
*vtx[]);

void polygon3d_f(BITMAP *bmp, int type, BITMAP *texture, int vc, V3D_f
*vtx[]);

---

✨ DESCRIPTION ✨

okay so the whole vibe: these two draw 3d polygons onto the bitmap you point at, using whatever rendering mode you asked for. slay.

but bestie, hear me — unlike the regular polygon() function, these routines do not support concave or self-intersecting shapes 💀. not their thing. they also can't draw onto mode-X screen bitmaps. so if you're dead set on writing 3d code in mode-X, the move is: draw onto a memory bitmap and then blit it to the screen. periodt.

also!! the width and height of the texture bitmap must be powers of two — but they can be different from each other. like, a 64x16 texture? totally fine ✨ a 17x3 one? absolutely not, no. 🙈

the vertex count parameter (vc) should be followed by an array containing the appropriate number of pointers to vertex structures: polygon3d() uses the fixed point V3D structure, while polygon3d_f() uses the floating point V3D_f structure. and these are defined as:

typedef struct V3D
{
   fixed x, y, z;       - position
   fixed u, v;          - texture map coordinates
   int c;               - color
} V3D;

typedef struct V3D_f
{
   float x, y, z;       - position
   float u, v;          - texture map coordinates
   int c;               - color
} V3D_f;

how the vertex data gets used depends on the rendering mode 👑

• the x and y values specify the position of the vertex in 2d screen coordinates.
• the z value is only required when doing perspective correct texture mapping, and it specifies the depth of the point in 3d world coordinates.
• the u and v coordinates are only required when doing texture mapping, and they specify a point on the texture plane to be mapped on to this vertex. the texture plane is an infinite plane with the texture bitmap tiled across it. each vertex in the polygon has a corresponding vertex on the texture plane, and the image of the resulting polygon in the texture plane gets mapped on to the polygon on the screen.

texels, and why u=32 hits different 🧚

we refer to pixels in the texture plane as texels. and here's the thing — each texel is a block, not just a point, and whole numbers for u and v refer to the top-left corner of a texel. this has a few implications, so let's unpack:

if you wanna draw a rectangular polygon and map a texture sized 32x32 on to it, you'd use the texture coordinates (0,0), (0,32), (32,32) and (32,0) — assuming the vertices are specified in anticlockwise order. the texture will then be mapped perfectly on to the polygon. 💅

however!! note that when we set u=32, the last column of texels seen on the screen is the one at u=31, and the same goes for v. this is because the coordinates refer to the top-left corner of the texels. in effect, texture coordinates at the right and bottom on the texture plane are exclusive. no cap.

there's another interesting point here 👀 — if you have two polygons side by side sharing two vertices (like the two parts of a folded piece of cardboard), and you wanna map a texture across them seamlessly, the values of u and v on the vertices at the join will be the same for both polygons. for example, if they're both rectangular, one polygon may use (0,0), (0,32), (32,32) and (32,0), and the other may use (32,0), (32,32), (64,32), (64,0). that would create a seamless join. obsessed.

of course you can specify fractional numbers for u and v to indicate a point part-way across a texel. and in addition, since the texture plane is infinite, you can specify larger values than the size of the texture. this can be used to tile the texture several times across the polygon. 🔥

the c value 🍓

the c value specifies the vertex color, and it's interpreted differently by various rendering modes. read the beginning of chapter "Polygon rendering" for a list of rendering types you can use with this function.

---

✨ SEE ALSO ✨

• triangle3d(3)
• quad3d(3)
• polygon(3)
• clip3d(3)
• cpu_capabilities(3)
• excamera(3)

---

ok that's the whole page, bestie, you're so welcome 💜

this was from Allegro, version 4.4.3, and it's the polygon3d(3) page — go forth and render some absolutely iconic 3d polygons, you main character 🌈⭐🦋