New document, describing the graphics libraries
git-svn-id: svn://svn.code.sf.net/p/sc2/code/trunk@676 8092fc87-c524-0410-9efc-e669fe64eaf9
This commit is contained in:
mcmartin
@@ -0,0 +1,260 @@
|
||||
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 includes
|
||||
an element "DataOffs", which, horrifyingly, appears to be
|
||||
a deliberate index past the end of the struct. Given a
|
||||
PFRAME_DESC x, (void *)(x[x->DataOffs]) is a void pointer
|
||||
castable to TFB_Image.)
|
||||
|
||||
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);
|
||||
|
||||
----
|
||||
|
||||
There are some obvious operations missing here. Creation and
|
||||
destruction of TFB_Images are the main gaps. The ability to 'wrap' a
|
||||
TFB_Canvas with a fresh TFB_Image would probably be nice too.
|
||||
|
||||
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);
|
||||
|
||||
----
|
||||
|
||||
Commentary on needed operations also mirrors that of TFB_Image.
|
||||
|
||||
|
||||
DRAWCMD LIBRARY
|
||||
-----------------
|
||||
|
||||
Documentation yet to be written. UQM code shouldn't really mess with
|
||||
the DrawCmd library directly.
|
||||
Reference in New Issue
Block a user