.\" Automatically generated by Pandoc 3.6.1
.\"
.TH "al_perspective_transform" "3" "" "Allegro reference manual"
.SH NAME
al_perspective_transform \- Allegro 5 API
.SH SYNOPSIS
.IP
.EX
#include \f[B]<allegro5/allegro.h>\f[R]

void al_perspective_transform(ALLEGRO_TRANSFORM *trans,
   float left, float top, float n,
   float right, float bottom, float f)
.EE
.SH DESCRIPTION
Like al_orthographic_transform(3) but honors perspective.
If everything is at a z\-position of \-near it will look the same as
with an orthographic transformation.
.PP
To use a specific horizontal field of view you can use the relation:
.IP
.EX
tan(hfov / 2) = (right \- left) / 2 / near
.EE
.PP
and therefore
.IP
.EX
near = (right \- left) / 2 / tan(hfov / 2)
.EE
.PP
Example 1:
.IP
.EX
   float w = 800, h = 450; \f[I]// assume our display is 800 x 450\f[R]
   float fov = tan(90 * ALLEGRO_PI / 180 / 2); \f[I]// 90 degree field of view\f[R]

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

   \f[I]// Set the camera z to +400 (which is exactly the near distance)\f[R]
   ALLEGRO_TRANSFORM camera;
   al_build_camera_transform(&camera, 0, 0, 400, 0, 0, 0, 0, 1, 0);
   al_use_transform(&camera);

   \f[I]// This will draw two rectangles at the left and right edge of the\f[R]
   \f[I]// screen and vertically centered. The x distance between them is 800\f[R]
   \f[I]// units, but the camera transform moves them 400 along z, so with\f[R]
   \f[I]// a 90° viewing angle both are visible.\f[R]
   al_draw_filled_rectangle(0, 200, 50, 250, red;
   al_draw_filled_rectangle(750, 200, 800, 250, red);
.EE
.PP
Example 2:
.IP
.EX
   float w = 800, h = 450; \f[I]// assume our display is 800 x 450\f[R]
   float fov = tan(90 * ALLEGRO_PI / 180 / 2); \f[I]// 90 degree field of view\f[R]
   float aspect = h / w;
   float zoom = 2; \f[I]// enlarge x 2\f[R]

   \f[I]// This projection is very different from the one in the first example.\f[R]
   \f[I]// Here we map the left and right edge of the screen to \-1 and +1. And\f[R]
   \f[I]// the y axis goes from \-1 at the bottom to +1 at the top, scaled by\f[R]
   \f[I]// the aspect ratio. We also add a zoom parameter so we can control\f[R]
   \f[I]// the visible portion of the scene independent of the field of view.\f[R]
   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);

   \f[I]// Moves everything by \-4 in the z direction.\f[R]
   ALLEGRO_TRANSFORM camera;
   al_build_camera_transform(&camera, 0, 0, 4, 0, 0, 0, 0, 1, 0);
   al_use_transform(&camera);

   \f[I]// At a z distance of 4 with a 90° hfov everything would be scaled\f[R]
   \f[I]// down to 25%. However we also zoom 2\-fold, so the final scaling is\f[R]
   \f[I]// 50%. This rectangle therefore will appear at a size of 400 x 225\f[R]
   \f[I]// pixel (assuming the display is 800 x 450).\f[R]
   al_draw_filled_rectangle(\-1, \-1, 1, 1, red);
.EE
.SH SINCE
5.1.3
.SH SEE ALSO
al_use_projection_transform(3), al_orthographic_transform(3)