Allegro^Pak is a collection of extra C functions for use with the Allegro library as mentioned on Wacko Software's Allegro programming page. In other words, it is an add-on Package for Allegro. Most of the package involves Z-buffering, but there are also some general-purpose 3D and non-3D functions. The main features of this package are Z-buffered versions of all of Allegro's polygon-rendering modes (including two new ones which are affine and perspective-correct texture-mapping that is both masked and lit) and z-buffered sprites (both flat ones and ones with depth-maps).

Allegro^Pak and its demos have the following low-level features:

• Z-buffering added to all of Allegro's polygon drawing modes.
  Z-buffering enables you to record the Z-depth of each pixel so when rendering a 3D objerct, you just draw the object, and the Z-buffering decides for you what is visible and what isn't.
• The inclusion of polygon rendering modes: POLYTYPE_ATEX_MASK_LIT and POLYTYPE_PTEX_MASK_LIT (z-buffered only).
  Now you can have masked texture that is illuminated. In Allegro, these are two seperate modes.
• 3D sprites (both with and without depth-maps). These sprites can be zoomed, rotated, drawn translucent or lit (you can even z-zoom and transparent z-blit the 3D sprite in one command).
  This is an ideal way of using bitmap-sprites to draw characters in a 3D world.

• Light-sourced gouraud shaded objects (with vertex-normals) drawn with Allegro's polygon drawer (this is done in one of the demos).
  This is when objects are illuminated according to how close they are to the lightsource, rather than which way the face is facing. Objects rendered this way look very smooth.
• Real-time (almost) light-sourced texture-mapped Z-buffered sphere rendering.
  A set of commands for rendering spheres in real-time.
• Fog Shading (this is done in one of the demos).
  The further away an object is from the viewer, the poorer its visibility.
• Full viewing-volume (fustrum) 3D polygon clipping (clips polygons to the X=Z, X=-Z, Y=Z, Y=-Z and near Z=K planes).
  This clips a polygon in 3D space to the portion of the screen that's visible.
• Miscellaneous 3D Functions (mostly for converting between Cartesian and Polar coordinates in 3D space).
  These are good for positioning objects on spheres.
• RGB <-> HSV functions that actually work, as well as RGB <-> HLS functions.
  Allegro's RGB <-> HSV functions do not work, so I provided an alternative.

Download Allegro^Pak

Allegro^Pak's current version is 1.0 beta 1a

You may also download compiled executable versions of the two demos that come with Allegro^Pak.

See also the Allegro^Pak Demos entry in the Allegro.cc depot.

Anything that is emphasised has been added since the last release of Allegro^Pak.

KNOWN BUGS:

• With texture-mapped spheres, whenever the light vector in ILIT space is {0,0,0} or in PLIT space, the light-sphere is exactly in the middle of a sphere, the program crashes with a page fault. To work around this, either don't have a zero ILIT light-vector, or don't place your lightsource in the middle of a sphere. Also, it is not a good idea to have your lightsource right on the surface of a sphere.
• The spheres will not be drawn correctly if their radius is greater than 181.019 ( = sqrt(0x7FFF.FFFF) ) . This is a limitation with the fixed-number format used in the sphere-rendering code.
• Sometimes, if polygons go too far in the Z direction (maybe the Z slope in the scanline is too large), the program may crash with an FPE in the polygon drawer's PTEX_* scanline filler. This also happens in Shawn's original Allegro code as well as my Z-buffered modification (which is here), but I have yet to conclusively prove that this one's not my fault.
• When rendering polygons using PTEX_LIT (and I think ATEX_LIT too), the light value wraps back to 255 when it has passed 0. This also happens in Shawn's original code, but as above, I've yet to find out who's bug it is. Try also with GCOL and GRGB. As a workaround, use some number greater than 0 for the minimum light.

KNOWN ISSUES:

• When compiling Allegro^Pak with the WIP version of Allegro 3.0, some of the functions do not work properly or cause a crash (this does not affect Allegro 2.2). Here is how to fix this problem:
  
  • Delete the asmdef.h file that came with Allegro^Pak.
  • In the directory /obj/djgpp/ located in the directory you compiled Allegro 3.0 in, there is a file called asmdef.inc. Copy this file into the directory you unzipped Allegro^Pak into.
  • Rename the copied file to asmdef.h
• All Z-buffers are an extra 4 bytes in size. This is so that when zooming depth-maps, I've optimised for the pentium by doing a division involving the next value so it would cause a crash if the value after the end of the z-buffer is a certain value. I have added a value in this extra entry that ensures it doesn't crash. See the comments on the relevant functions for how I have worked around this one.
• Translucent objects must be depth-sorted and drawn last because of Z-buffering. Overlapping translucent objects are not rendered correctly because the z-buffer prevents pixels behind a translucent object (with its recorded Zs) from being drawn.
• The sphere rendering functions only render isometric spheres (ie. they are not perspective-distorted). You notice this the most with the masked-texturing modes (the back of the sphere remains at the same position relative to the front when moved around in screen-space).

1.0 beta 1a:

• Corrected the spelling of frustum (was spelled 'fustrum') and longitude (was spelled 'longtitude'). If you have written any code that uses these functions, then you will have to change the spelling in your code (this isn't too hard if your text-editor has a search-and-replace function).
• sphere_f() checks to see if the pointer to the rotation matrix is NULL before it converts the rotation matrix to the format required by sphere_f(). This means that sphere_f() no longer crashes under DOS.
• Documentation contains required and recommended setup.
• Included instructions on how to get Allegro^Pak to work with Allegro 3.0 WIP (it works fine with Allegro 2.2).
• The documentation now explains how masked areas are handled in flat zprites, and how to simulate masks in zprites.
• In SPH_DEMO, a bug is fixed that meant the light-sphere got drawn once per other sphere instead of once per frame.
• In SPH_DEMO, the spheres are now depth-sorted so that the frontmost gets drawn first. This reduces the average number of times a pixel's light and texture must be re-calculated (in Z-buffered systems, drawing the frontmost object first is generally a good idea). The speed improvements are most noticed when using fancy lighting and texturing modes.
• Better feedback in 3DSPDEMO.
• In the demos, you can now access the display of the key commands by pressing F12.

1.0 beta 1:

• First version made available to the general public.

Anything that is emphasised has been added since the last release of Allegro^Pak.

• Turn this into a proper library so you would just have to do something like "#include <algpk.h>" and link in libalgpk.a instead of messing around with all of Allegro^Pak's files.
• At the moment, I'm not too happy with the speed of some of the stuff (notably the Z-buffered stuff), and have since then learned that using self-modifying code on a Pentium is not a good idea (too many Instruction-cache re-loads), and that I can use the %ebp register (the reason I didn't use it was to maintain consistency with Shawn's code). I am also considering giving all of Allegro's polygon rendering modes a complete overhaul, or writing a complete polygon renderer from scratch that includes support for 3D rendering hardware. Also, triangles and quads are faster than general-purpose polygons. This is due to the number of times the gradient changes as you travel the y axis.
• Self-defined depth-maps (use a 256-greyscale (or 64-greyscale) image to represent the depths of a sprite). These can be stored in Allegro's Datafiles. At the moment, you would have to write your own function for converting a bitmap into a depth-map.
• Z-buffered blit that just writes Z-information without checking.
• A command that clears just part of a Z-buffer. Then with this and Z-buffered blit, I could have a dirty-rectangle-based 3D sprite game.
• Perhaps do a MODE-X version of the z-buffered polygon renderers or zprite drawers. However, I believe most people use doing 3D graphics on a PC use double-buffering anyway to draw their polys, so I may drop all support for writing directly to the screen. This will speed things up because I no longer have to use instructions with a selector prefix to select the screen memory. I think I should keep screen support for the zprites, as these can also be useful for 2D games.
• Fixed-point versions of reverse_persp_project_f() and clip_poly_to_fustrum_f()
• More efficient version of clip_poly_to_fustrum()
• clip_object_to_fustrum()
• HLS <-> HSV conversion functions.
• Fixed point versions of colour-space conversion functions.
• Make the colourspace-conversion functions use 0-1 for continuous RGB values instead of the discrete 0-63.
• Write an Assembler version of the sphere rendering algorithms.
• SPHERESHADE_MLIT lighting mode for having multiple light-sources on the spheres.
• Multicoloured light-sources for spheres.
• Functions for generating gamma-adjusted 256-colour palettes that try to have as much of the colour-spectrum that you can get in 256 colours.
• perspective-distorted spheres.
• When wrapping texture to the back of a sphere, make it so that it uses the part of the bitmap starting at size+offset.
• Support for more types of Z-buffer.
• Support hardware Z-buffering.
• [draw|displace]_[flat_]trans_lit_zprite[_[v|h|vh]_flip](), etc.
• stretch_zprite(): Unlike displace_zprite, this actually shrinks and enlarges a zprite in 3D space.
• Z-buffered rendering that does not record the resulting Z (useful for drawing lots of depth-sorted zprites on a static scene). Or one that does not check the Zs (if you know the entire object will be visible).
• Pentium optimised version of the zoomer that does not write scanline-fillers.
• A function for automatically generating a good palette to use in a fog-mapped scene.

Allegro^Pak Demos

Compiled and executable versions of Allegro^Pak's two demos. See also the Allegro^Pak Demos entry in the Allegro.cc depot. So far, these are the only programs known to have been done with Allegro^Pak.

Feedback:
Use this link to leave some feedback for this webpage.

Last update: Sat 22 Jan 2005

Back to Wacko Software's Allegro Programming page