al_perspective_transform(3alleg5) al_perspective_transform(3alleg5)

# 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¶

Like al_orthographic_transform(3alleg5) but honors perspective. If everything is at a z-position of -near it will look the same as with an orthographic transformation.

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)
```

Example 1:

```
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);
```

Example 2:

```
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);
```

5.1.3