.\" Automatically generated by Pandoc 2.17.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "al_perspective_transform" "3alleg5" "" "Allegro reference manual" ""
.hy
.SH NAME
.PP
al_perspective_transform - Allegro 5 API
.SH SYNOPSIS
.IP
.nf
\f[C]
#include <allegro5/allegro.h>

void al_perspective_transform(ALLEGRO_TRANSFORM *trans,
   float left, float top, float n,
   float right, float bottom, float f)
\f[R]
.fi
.SH DESCRIPTION
.PP
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.
.PP
To use a specific horizontal field of view you can use the relation:
.IP
.nf
\f[C]
tan(hfov / 2) = (right - left) / 2 / near
\f[R]
.fi
.PP
and therefore
.IP
.nf
\f[C]
near = (right - left) / 2 / tan(hfov / 2)
\f[R]
.fi
.PP
Example 1:
.IP
.nf
\f[C]
   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\[de] viewing angle both are visible.
   al_draw_filled_rectangle(0, 200, 50, 250, red;
   al_draw_filled_rectangle(750, 200, 800, 250, red);
\f[R]
.fi
.PP
Example 2:
.IP
.nf
\f[C]
   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\[de] 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);
\f[R]
.fi
.SH SINCE
.PP
5.1.3
.SH SEE ALSO
.PP
al_use_projection_transform(3alleg5), al_orthographic_transform(3alleg5)