NAME

       polygon3d,  polygon3d_f  -  Draws  a  3d  polygon  onto the specified bitmap. Allegro game
       programming library.

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

       Draw 3d polygons onto the specified bitmap, using the specified rendering mode. Unlike the
       regular  polygon()  function,  these  routines  don't support concave or self-intersecting
       shapes, and they can't draw onto mode-X screen bitmaps (if you want to write  3d  code  in
       mode-X,  draw  onto  a memory bitmap and then blit to the screen). The width and height of
       the texture bitmap must be powers of two, but can be different, eg.  a  64x16  texture  is
       fine,  but  a  17x3  one  is not. 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.  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 is 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
       specifies the depth of the point in 3d world coordinates.

       The  `u'  and  `v' coordinates are only required when doing texture mapping, and 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 will be mapped on to the polygon on the screen.

       We  refer  to  pixels  in  the  texture plane as texels. 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. If you want to draw a rectangular polygon and map a texture sized 32x32
       on to it, you would 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.

       There is another interesting point here. If you have two polygons side by side sharing two
       vertices (like the two parts of folded piece of cardboard), and you want to 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 are 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). This
       would create a seamless join.

       Of course you can specify fractional numbers for u and v  to  indicate  a  point  part-way
       across  a  texel. 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  specifies  the  vertex  color,  and is 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(3alleg4),       quad3d(3alleg4),       polygon(3alleg4),       clip3d(3alleg4),
       cpu_capabilities(3alleg4), excamera(3alleg4)