path: root/doc/devel/gfxlib

		      The TFB Graphics Libraries

	 Initial documentation by Michael Martin, 4 Feb 2003

The graphics system in UQM has three major subsystems:

- The "legacy" system, which most of the core code uses.  This
  involves the foo_blt () routines in 3do_blt.c, and the data
  types CONTEXT, FRAME, DRAWABLE, and possibly others.  I'm
  less familiar with this code, and want to eradicate as much of it as
  I can, but for now, its lowest level has been rewritten as direct
  calls to:

- The TFB_Draw* commands, documented below in great detail.  These
  routines deal with the datatype TFB_Image, and the more primitive
  TFB_Canvas.  They also support drawing to one of several 'screens',
  but since only one thread should be allowed to touch the screen,
  the TFB_DrawScreen routines end up constructing inputs to:

- The DCQ/DrawCommand library.  This is a ring queue with commands for
  rendering graphics on the actual screen.  It interacts to some
  degree with the CONTEXT datatype, but otherwise is defined entirely
  in terms of TFB_Images and TFB_Canvases.

			  THE LEGACY LIBRARY
			 --------------------

The datatypes the code uses directly are CONTEXT, FRAME, and FONT, all
of which are really pointers to void.  Pointers to those are PCONTEXT,
PFRAME, and PFONT.  Then there's DRAWABLE, which is a DWORD, and its
pointer type PDRAWABLE. (These are defined in sc2code/libs/gfxlib.h.)
I'm not sure how DRAWABLE values are transformed into actual drawable
entities.

The full structures for these are in various files in
sc2code/libs/graphics.

context.h:  defines CONTEXT_DESC and PCONTEXT_DESC (and the equivalent
            CONTEXTPTR -- insert various sorts of incomprenshible
            muttering here),

display.h:  defines a DISPLAY_INTERFACE and PDISPLAY_INTERFACE type (as
            well as a global _pCurDisplay).

drawable.h: defines FRAME_DESC and DRAWABLE_DESC, and the pointer
            types PFRAME_DESC and PDRAWABLE_DESC.  FRAME_DESC has a
            TFB_Image pointer as a member.  DRAWABLE_DESC currently
            still uses a rather annoying technique where the last
            member of a struct is a 1-element array, more memory than
            that is actually allocated, and the array's bounds are
            deliberately overflowed to get at multiple frames.

font.h:     defines FONT_DESC and PFONT_DESC.

(Details on how all these data types work is forthcoming.)

			 THE TFB_DRAW LIBRARY
			----------------------

The TFB_Draw commands have a single header file:
sc2code/libs/graphics/tfb_draw.h.  This file declares the following
data types:

SCREEN: This is an enum, naming the various screens that the DrawCmd
        library can draw to.  Valid values at present are
        TFB_SCREEN_MAIN, TFB_SCREEN_EXTRA, and TFB_SCREEN_TRANSITION.
        These correspond to various objects that are of type TFB_Canvas.

	(The maximal number of screens is provided by a bogus last
        element, TFB_GFX_NUMSCREENS.  Keep that as the last element
        and the allocators will operate properly regardless of any
        screens you may later want to add.)

TFB_Canvas: This is, for the purposes of most of the code, a void
            pointer.  The implementations of TFB_DrawCanvas commands
            cast them to the appropriate type.  (The only
            implementation of these commands casts them to
            SDL_Surface*.)

TFB_Palette: Four UBYTES, r, g, b, and 'unused'.  This is designed at
             present to be directly castable to SDL_Color, which most
             things do.  We should probably do something about that at
             some point.

TFB_Image: The most important image structure.  This has two
           TFB_Canvases (one for the 'core' image, one for a scaled
           version of it), a pointer to a TFB_Palette array, a
           colormap index, a scaling constant, a Mutex from the
           threading library (to ensure internal consistency if
           multiple threads are doing stuff), and a 'dirty bit' which
           means that, if the image is scaled, the ScaledImg needs to
           be recomputed.

TFB_DrawScreen
--------------

When you wish to draw graphics directly on the screen, you call these
routines, which enqueue the DrawCommands:

----

void TFB_DrawScreen_Line (int x1, int y1, int x2, int y2, 
			  int r, int g, int b, 
			  SCREEN dest);

Draws a line from (x1, y1)-(x2, y2) of a color specified by r, g, and
b on the specified screen.

We have a known bug here in that if a corner of one of these lines is
outside of the context's clipping rectangle, the slope of the line may
change.

----

void TFB_DrawScreen_Rect (PRECT rect, 
			  int r, int g, int b, 
			  SCREEN dest);

Draws a (filled) rectangle with the specified color on the destination
screen.  PRECT is part of the legacy library.

void TFB_DrawScreen_Copy (PRECT r, SCREEN src, SCREEN dest);

Copies data between screens.  The PRECT defines the region to copy.
This can be handy in saving and restoring background information.

----

void TFB_DrawScreen_Image (TFB_Image *img, 
			   int x, int y, 
			   BOOLEAN scaled, 
			   TFB_Palette *palette, 
			   SCREEN dest);

void TFB_DrawScreen_FilledImage (TFB_Image *img, 
				 int x, int y, 
				 BOOLEAN scaled, 
				 int r, int g, int b, 
				 SCREEN dest);

These two routines draw images.  img, x, and y are all straightforward
(x and y refer to the upper left of the image), and scaled indicates
whether or not the NormalImg or ScaledImg should be used, and dest
names the target screen.

For TFB_DrawScreen_Image, the 'palette' argument refers to a
256-element array of TFB_Palette that describes the palette to use.
(The default is cached in TFB_Image itself.)  Various techniques are
used to cache the palette values to keep spurious palette-switch
commands from flooding the DrawCmd queue.  However, switching the
palette many times per frame is likely to seriously degrade
performance.

TFB_DrawScreen_FilledImage draws every non-transparent pixel in img in
the color specified by r, g, b.  (Fonts and some menus do this.)

----

void TFB_DrawScreen_WaitForSignal (void);

Puts this thread to sleep until all commands queued to this point are
executed.  Mostly used to keep from spamming the DrawCmd queue, and to
ensure proper operation of the next two routines.

----

void TFB_DrawScreen_CopyToImage (TFB_Image *img, 
				 PRECT lpRect, 
				 SCREEN src);

Load the pixels from the rectangle lpRect in screen src into img.  If
you're actually working with the pixels directly, you'll want to do a
TFB_DrawScreen_WaitForSignal () to ensure the image has actually been
updated.  (If you're just passing it to other TFB_DrawScreen commands,
that's unnecessary, because ordering within a thread is guaranteed.)

----

void TFB_DrawScreen_DeleteImage (TFB_Image *img);

Deallocates all memory associated with img.  This REALLY doesn't
belong here.  It should be a TFB_DrawImage command, with a requirement
that you WaitForSignal lfirst.

----

TFB_DrawImage
-------------

These routines are similar to a subset of the TFB_DrawScreen commands,
except that instead of drawing on the screen at some later time, they
draw directly and immediately onto a TFB_Image.  The arguments all
mean the same things as they did for TFB_DrawScreen.

----

void TFB_DrawImage_Line (int x1, int y1, int x2, int y2, 
                         int r, int g, int b, 
			 TFB_Image *dest);

void TFB_DrawImage_Rect (PRECT rect, 
			 int r, int g, int b, 
			 TFB_Image *image);

void TFB_DrawImage_Image (TFB_Image *img, 
			  int x, int y, 
			  BOOLEAN scaled, 
			  TFB_Palette *palette, 
			  TFB_Image *target);

void TFB_DrawImage_FilledImage (TFB_Image *img, 
				int x, int y, 
				BOOLEAN scaled, 
				int r, int g, int b, 
				TFB_Image *target);

----

TFB_DrawCanvas
--------------

These routines are, quite literally, identical in every way to the
TFB_DrawImage routines, except that they draw on TFB_Canvases instead.
They are defined in graphics-library-specific locations.  There is, at
present, only one implementation of these, in
libs/graphics/sdl/canvas.c.

void TFB_DrawCanvas_Line (int x1, int y1, int x2, int y2, 
			  int r, int g, int b, 
			  TFB_Canvas dest);

void TFB_DrawCanvas_Rect (PRECT rect, 
			  int r, int g, int b, 
			  TFB_Canvas image);

void TFB_DrawCanvas_Image (TFB_Image *img, 
			   int x, int y, 
			   BOOLEAN scaled, 
			   TFB_Palette *palette, 
			   TFB_Canvas target);

void TFB_DrawCanvas_FilledImage (TFB_Image *img, 
				 int x, int y, 
				 BOOLEAN scaled, 
				 int r, int g, int b, 
				 TFB_Canvas target);

----

Creation and Destruction of TFB_Images, TFB_Canvases, and TFB_Palettes
----------------------------------------------------------------------

Various commands exist for creating and destroying the TFB_Draw data
types.  The concept of "ownership" is critical here.  If a data object
owns a pointer inside of it, that pointer's referent is deallocated
when the data object is deallocated.  If a pointer variable owns its
referent, it's permissible to delete it.  

TFB_Canvas and TFB_Palette are primitives.  TFB_Image owns NormalImg,
ScaledImg, and Palette, and will delete them when it is itself
deleted.

That said, here are the routines:

---

TFB_Image *TFB_DrawImage_New (TFB_Canvas canvas)

Creates a new TFB_Image, which the caller then owns.  The caller must
own the canvas, and transfers ownership of that canvas to the image.
The Palette value is automatically created (and the image owns it);
ScaledImg will be NULL until you scale the image and draw it to the
screen.

---

void TFB_DrawImage_Delete (TFB_Image *image)

Deletes the image, and all non-NULL components.  You must own the
image you delete.

---

TFB_Canvas TFB_DrawCanvas_New_TrueColor (int w, int h, BOOLEAN has_alpha);

TFB_Canvas TFB_DrawCanvas_New_Paletted (int w, int h, 
					TFB_Palette *palette, 
					int transparent_index);

These create new TFB_Canvases, which the caller will then own.  Width
and height are straightforward.  The TrueColor variant produces Canvases
with the same color depth and pixel format as the screen.  The
has_alpha flag indicates whether or not the canvas has an alpha
channel.

The Paletted variant produces 8-bit paletted canvases.  The palette
argument is optional (it can be NULL, in which case you'll need to set
it later - TFB_Images tend to do this when drawn), as is the
transparent_index (if -1, there is no transparency; otherwise, it's
the index of the transparent color).

---

TFB_Canvas TFB_DrawCanvas_ToScreenFormat (TFB_Canvas canvas);

Returns a canvas that, if possible, matches the graphics configuration
of the screen.  You must own the source canvas.  If the conversion is
possible, it makes the conversion, deletes its argument, and returns
the converted version; if conversion is not possible, the canvas is
returned intact.

Regardless of success or failure, the caller owns the result.

---

TFB_Palette *TFB_DrawCanvas_ExtractPalette (TFB_Canvas canvas);

Allocates and returns a 256-entry TFB_Palette array that describes the
palette of the canvas, or returns NULL if the canvas is true-color.
If the result is non-NULL, the caller owns the result.  The caller
need not own canvas.


			   DRAWCMD LIBRARY
			  -----------------

Documentation yet to be written.  UQM code shouldn't really mess with
the DrawCmd library directly.