AL_PERSPECTIVE_TRANSFORM(3)

🎀 al_perspective_transform(3) 🎀

okay bestie, this is the Library Functions Manual page for al_perspective_transform, and it’s literally an Allegro 5 API moment. perspective has entered the chat 💅

---

💖 NAME 💖

al_perspective_transform — Allegro 5 API

---

✨ SYNOPSIS ✨

#include <allegro5/allegro.h>

void al_perspective_transform(ALLEGRO_TRANSFORM *trans,
   float left, float top, float n,
   float right, float bottom, float f)

---

🦋 DESCRIPTION 🦋

so here’s the tea: al_perspective_transform is like al_orthographic_transform(3) but it honors perspective. If everything is at a z-position of -near, it will look the same as with an orthographic transformation. no cap, that’s the whole vibe check 🫶

You pass in trans, left, top, n, right, bottom, and f — and yes, bestie, those are the exact parameter names, we’re not out here renaming anything 💀

🌸 The formulas 🌸

To use a specific horizontal field of view you can use the relation:

tan(hfov / 2) = (right - left) / 2 / near

and therefore

near = (right - left) / 2 / tan(hfov / 2)

math girlies rise 🧚

🍓 Example 1 🍓

this one is giving “camera z goes brrr” ✨

float w = 800, h = 450; // assume our display is 800 x 450
float fov = tan(90 * ALLEGRO_PI / 180 / 2); // 90 degree field of view

// Our projection goes from 0/0 to w/h with the near parameter set
// for a 90 degree horizontal viewing angle.
ALLEGRO_TRANSFORM projection;
al_identity_transform(&projection);
al_perspective_transform(&projection, 0, 0,
 w / 2 / fov,
 w, h,
 2000);
al_use_projection_transform(&projection);

// Set the camera z to +400 (which is exactly the near distance)
ALLEGRO_TRANSFORM camera;
al_build_camera_transform(&camera, 0, 0, 400, 0, 0, 0, 0, 1, 0);
al_use_transform(&camera);

// This will draw two rectangles at the left and right edge of the
// screen and vertically centered. The x distance between them is 800
// units, but the camera transform moves them 400 along z, so with
// a 90° viewing angle both are visible.
al_draw_filled_rectangle(0, 200, 50, 250, red;
al_draw_filled_rectangle(750, 200, 800, 250, red);

<tone>quick note bestie: that al_draw_filled_rectangle(0, 200, 50, 250, red; line is exactly how it appears in the original — we are keeping it character-for-character, periodt 💅

🦄 Example 2 🦄

this one is highkey different from the first example — it maps left/right to -1 and +1, scales y by aspect ratio, and adds a zoom parameter 🌈

float w = 800, h = 450; // assume our display is 800 x 450
float fov = tan(90 * ALLEGRO_PI / 180 / 2); // 90 degree field of view
float aspect = h / w;
float zoom = 2; // enlarge x 2

// This projection is very different from the one in the first example.
// Here we map the left and right edge of the screen to -1 and +1. And
// the y axis goes from -1 at the bottom to +1 at the top, scaled by
// the aspect ratio. We also add a zoom parameter so we can control
// the visible portion of the scene independent of the field of view.
ALLEGRO_TRANSFORM projection;
al_identity_transform(&projection);
al_perspective_transform(&projection,
   -1 / zoom, aspect / zoom,
   1 / fov,
   1 / zoom, -aspect / zoom,
   2000);
al_use_projection_transform(&projection);

// Moves everything by -4 in the z direction.
ALLEGRO_TRANSFORM camera;
al_build_camera_transform(&camera, 0, 0, 4, 0, 0, 0, 0, 1, 0);
al_use_transform(&camera);

// At a z distance of 4 with a 90° hfov everything would be scaled
// down to 25%. However we also zoom 2-fold, so the final scaling is
// 50%. This rectangle therefore will appear at a size of 400 x 225
// pixel (assuming the display is 800 x 450).
al_draw_filled_rectangle(-1, -1, 1, 1, red);

iconic behavior honestly 🔥

---

🌟 SINCE 🌟

Available since 5.1.3 iykyk 🎀

---

🔗 SEE ALSO 🔗

• al_use_projection_transform(3)
• al_orthographic_transform(3)

---

footer check, bestie 🫶: the original footer is Allegro reference manual + al_perspective_transform(3), and there’s no date listed, so we’re not inventing one. slay 💜