Appendix A - Data Structures

This appendix describes the data structures defined and used within 
the TMS340 Graphics Library. The following is a list of all the
structure types to be discussed:

Structure Type 	Description
BITMAP		Bit map (actually a two-dimensional pixel array)
CONFIG		Information about display system and graphics
		mode
ENCODED_RECT	Header for image compressed by encode_rect 
		function
ENVIRONMENT	Information about drawing environment
ENVTEXT		Information about text environment
FONT		Header for a bit-mapped font
FONTINFO	Information about a bit-mapped font
MODEINFO	Information about a particular graphics mode
OFFSCREEN_AREA	Information about a particular off-screen buffer
PAGE		Information about a particular video page
PALET 		Information about a particular palette entry
PATTERN		Information about a particular area-fill pattern

Certain library functions retrieve information about the graphics 
environment and copy that information into one of the structures 
listed above. The following is a list of these functions and the structures
they use to present information to the application program:

Function		Structure Type
get_config		CONFIG
get_env 		ENVIRONMENT
get_fontinfo		FONTINFO
get_modeinfo		MODEINFO
get_offscreen_memory	OFFSCREEN_AREA
get_palet		PALET

Note that the definitions of the structure types above may 
change in subsequent revisions of TIGA and the TMS340 
Graphics Library. To minimize the impact of 
such revisions, write your application programs to refer to the 
elements of the structure symbolically by their field names, 
rather than as offsets from the start of the structure. The include 
files provided with the library and with 
TIGA will be updated, as necessary, in future revisions 
to track any such changes in data structure definitions.

Within the graphics library, information about the graphics 
environment is available in the form of global variables 
that are structures. The global variables and the corresponding 
structure types are listed below:

Global Variable	Structure Type	Global Variable Description
config		CONFIG		Information about display
				system and current
				graphics mode
DEFAULT_PALET[] PALET		Default 16-color palette
env		ENVIRONMENT	Current drawing environment
envtext 	ENVTEXT 	Current text environment
*modeinfo	MODEINFO	Pointer to information about
				current graphics mode
*offscreen	OFFSCREEN_AREA	Pointer to array of off-screen
				buffers available in current
				graphics mode
*page		PAGE		Pointer to array of video pages
				available in current graphics
				mode
palet[] 	PALET		Array of current palette entries
pattern 	PATTERN 	Current area-fill pattern
*sysfont	FONT		Pointer to system font

An asterisk in the left column indicates that the associated variable is a 
pointer; a pair of square brackets indicates that the variable is an array. 
These global variables are accessible to all library functions and to any 
proprietary library extensions added by the user. While application 
programs running under the TMS340 Graphics Library may also
directly access these globals, applications running in the TIGA environment 
cannot. If emulation of the TIGA environment is important 
to your applications, access the library globals indirectly through inquiry
functions such as get_config and get_env. This practice will enhance 
the portability of applications between the graphics library and TIGA.

The type PTR, which appears in several of the structure 
definitions that follow, is defined as follows:

      typedef unsigned long PTR;

Type PTR is a 32-bit pointer to a location in the 
TMS340 graphics processor's memory.

A.1	BITMAP Structure Definition

The BITMAP data structure contains information describing 
a two-dimensional array of pixels. The following is the 
C typedef statement describing the structure:

typedef struct 
{
     PTR addr;			/* pixel array base address */
    unsigned short pitch;	/* pitch in bits */
    unsigned short xext, yext;	/* x and y extents */
    unsigned short psize;	/* pixel size in bits */
} BITMAP;            

The fields of the data structure are utilized as follows:

addr	32-bit base address of pixel array in TMS340 graphics 
	processor's memory

pitch	Difference in starting addresses between adjacent rows
	of pixel array

xext	The extent of pixel array in x dimension (pixels per row)

yext	The extent of pixel array in y dimension (number of rows)

psize	The depth (number of bits per pixel) of pixel array

The BITMAP structure is used in the definition of the ENVIRONMENT 
structure. For more information, refer to the description of the get_env
function in Chapter 7.

A.2	CONFIG Structure Definition

The CONFIG data structure contains information about the display system and 
graphics mode. The following is the C typedef  statement describing the 
structure:

typedef struct 
{
    unsigned short version_number;    	/* TIGA revision number */
    unsigned long comm_buff_size;     	/* undefined in graphics library */
    unsigned long sys_flags;		/* coprocessor presence flags */
    unsigned long device_rev;	       /* GSP silicon revision number */
    unsigned short num_modes;	       /* number of graphics modes */
    unsigned short current_mode;      	/* current graphics mode */
    unsigned long program_mem_start;  	/* start of program memory */
    unsigned long program_mem_end;    	/* end of program memory */
    unsigned long display_mem_start;  	/* start of display memory */
    unsigned long display_mem_end;    	/* end of display memory */
    unsigned long stack_size;	       /* max. stack size in bytes */
    unsigned long shared_mem_size;    	/* undefined in graphics library */
    HPTR shared_host_addr;		/* undefined in graphics library */
    PTR shared_gsp_addr;	      	/* undefined in graphics library */
    MODEINFO mode;			/* graphics mode information */
} CONFIG;

The HPTR type is a 32-bit pointer to a location in the host processor's memory. 


The graphics library's global variable config is a structure of type CONFIG. 
This global contains information describing the display system and the current 
graphics mode. For more information on the CONFIG structure, refer to the 
description of the get_config function in Chapter 6.

A.3	ENCODED_RECT Structure Definition

The ENCODED_RECT data structure defines the header information
at the beginning of a compressed image encoded by the encode_rect 
function. The following is the C typedef statement describing 
the structure:

typedef struct 
{
    unsigned short magic;	/* magic number */
    unsigned long length;	/* length of data in bytes */
    unsigned short scheme;	/* encoding scheme */
    short width, height;	/* dimensions of image rectangle */
    short psize;		/* pixel size of image */
    short flags;		/* usage varies with scheme */
    unsigned long clipadj;	/* x-y clipping adjustments */
} ENCODED_RECT;

For more information, refer to the description of the encode_rect 
function in Chapter 7.

A.4	ENVIRONMENT Structure Definition

The ENVIRONMENT data structure specifies the values of the
parameters in the drawing environment. The following is the C
typedef statement describing the structure:

typedef struct 
{
    unsigned long xyorigin;		/* x-y drawing origin */
    unsigned long pensize;		/* width and height of pen */
    BITMAP *srcbm, *dstbm;		/* source and destination bit maps */
    unsigned long stylemask;		/* line-style pattern */
} ENVIRONMENT;

The graphics library's global variable env is a structure of type 
ENVIRONMENT and contains information describing the current 
drawing environment. The ENVIRONMENT structure is also the format
in which the get_env function retrieves the information describing 
the current drawing environment. For more 
information, refer to the description of the ENVIRONMENT data 
structure in the description of the get_env function in Chapter 7.

A.5	ENVTEXT Structure Definition

The ENVTEXT data structure contains information describing 
the current text environment. The following is the C 
typedef statement describing the structure:

typedef struct
{
    short installed;	/* number of fonts installed */
    short allocated;	/* number of slots allocated */
    FONT **font;	/* pointer to font table */
    FONT *selected;	/* pointer to current font */
    short align;	/* alignment (top left or baseline) */
    short charextra;	/* additional intercharacter spacing */
    long effects;	/* special effects */
    short xposn, yposn; /* current text x-y coordinates */
} ENVTEXT;

The graphics library's global variable envtext is a structure
of type ENVTEXT that describes the current text attributes 
and provides access to the installed 
fonts. The fields of the ENVTEXT structure are utilized as follows:

installed 	The number of fonts currently installed in the font 
		table (in addition to font 0, which is permanently installed)

allocated 	The maximum number of fonts that can be installed in 
		the font table, in addition to font 0

font		A pointer to the start of the font table, which is a
		table of pointers to all currently installed fonts

selected 	A pointer to the currently selected font

align		Text alignment attribute (0 = align to top left
		corner of first character in string, 1 = align to
		character origin at base line)

charextra 	Extra intercharacter spacing attribute (value added 
		to default spacing specified in font structure)

effects 	Reserved for future use

xposn	       x coordinate of position at which next call to
	       text_outp will start printing

yposn	       y coordinate of position at which next
	       call to text_outp will start printing

By convention, the allocated field above must contain a 
value of 16 or greater. In other words, the font table will 
always be large enough to permit at least 
16 fonts to be installed, in addition to font 0, which is 
the permanently installed system font.

A.6	FONT Structure Definition

The FONT data structure defines the header information
at the start of a bit-mapped font. The following is the C 
typedef statement describing the structure:

typedef struct
{
    unsigned short magic;	/* font type code */
    long length;	/* length of font in bytes */
    char facename[30];	/* string containing name of font */
    short deflt	;	/* ASCII code of default character */
    short first;	/* ASCII code of first character */
    short last; 	/* ASCII code of last character */
    short maxwide;	/* maximum character width */
    short maxkern;	/* maximum character kerning amount */
    short charwide;	/* width of characters (0 if proportional) */
    short avgwide;	/* average width of characters */
    short charhigh;	/* character height */
    short ascent;	/* ascent (how far above base line) */
    short descent;	/* descent (how far below base line) */
    short leading;	/* leading (row bottom to next row top) */
    long rowpitch;	/* bits per row of char patterns */
    long oPatnTbl;	/* bit offset to pattern table */
    long oLocTbl;	/* bit offset to location table */
    long oOwTbl;	/* bit offset to offset/width table */
} FONT;

The graphics library's global variable sysfont  is a pointer to the system 
font, which begins with a header of type FONT. The FONT 
structure is also used in the definition of the ENVTEXT and 
FONTINFO structures. For more information, 
refer to the discussion of the FONT structure in Chapter 5.

A.7	FONTINFO Structure Definition

The FONTINFO structure defines the format in which the
get_fontinfo function retrieves information describing the 
designated font. The following is the C 
typedef  statement describing the structure:

typedef struct
{
    char facename[30];	/* string containing name of font */
    short deflt;	/* ASCII code of default character */
    short first;	/* ASCII code of first character */
    short last; 	/* ASCII code of last character */
    short maxwide;	/* maximum character width */
    short avgwide;	/* average width of characters */
    short maxkern;	/* maximum kerning amount */
    short charwide;	/* width of characters (0=proportional) */
    short charhigh;	/* character height */
    short ascent;	/* ascent (how far above base line) */
    short descent;	/* descent (how far below base line) */
    short leading;	/* leading (row bottom to next row top) */
    FONT *fontptr;	/* address of font in GSP memory */
    short id;		/* font identifier (font table index) */
} FONTINFO;

The FONTINFO structure is the format in which the get_fontinfo 
retrieves the information describing the specified installed font. 
For more information, refer to the description of the get_fontinfo 
function in Chapter 6.

A.7	MODEINFO Structure Definition

The MODEINFO data structure contains information 
describing a particular graphics mode. The following is the C typedef
statement describing the structure:

typedef struct
{
    unsigned long disp_pitch;	/* display pitch */
    unsigned short disp_vres;	/* number of scan lines */
    unsigned short disp_hres;	/* pixels per scan line */
    short screen_wide;		/* screen width in centimeters */
    short screen_high;		/* screen height in centimeters */
    unsigned short disp_psize;	/* pixel size in bits */
    unsigned long pixel_mask;	/* pixel mask */
    unsigned short palet_gun_depth;  /* bits per gun */
    unsigned long palet_size;	/* number of palette entries */
    short palet_inset;		/* palette offset from frame */
    unsigned short num_pages;	/* number of display pages */
    short num_offscrn_areas;	/* number of offscreen buffers */
    unsigned long wksp_addr;	/* offscreen workspace address */
    unsigned long wksp_pitch;	/* offscreen workspace pitch */
    unsigned short vram_block_write;  /* VRAM block write flag */
} MODEINFO;

The graphics library's global variable modeinfo is a pointer to a structure of 
type MODEINFO that describes the current graphics mode. The MODEINFO structure 
is the format in which the get_modeinfo function retrieves the information 
describing the specified graphics mode. Also, the MODEINFO structure is used in 
the definition of the CONFIG structure. For more information, refer to the 
description of the get_modeinfo function in Chapter 6.

	OFFSCREEN_AREA Structure Definition

The OFFSCREEN_AREA structure contains information describing a particular 
off-screen buffer area within the display memory. The following is the C 
typedef  statement describing the structure:

typedef struct 
{
    PTR addr;			/* base address of off-screen buffer */
    unsigned short xext, yext;	/* x and y extents of buffer */
} OFFSCREEN_AREA;

By convention, the pitch and pixel size of an off-screen buffer are always 
identical to those used for the display. These values can be 
obtained from the mode.disp_pitch and mode.disp_psize fields 
of the CONFIG structure retrieved by 
the get_config function.

The graphics library's global variable offscreen is a pointer to an 
array of type OFFSCREEN_AREA that specifies all the 
off-screen buffers available in the current graphics mode. 
For more information, refer to the discussion of the 
get_offscreen_memory function in Chapter 6.

A.10	PAGE Structure Definitions

The PAGE data structure contains information describing a particular 
video page (or frame buffer). The following is the C typedef
statement describing the structure:

typedef struct 
{
    unsigned long BaseAddr;   	/* base address of start of page */
    unsigned long DpyStart; 	/* display start value of page */
} PAGE;

The graphics library's global variable page is a pointer to an 
array of type PAGE that describes all the video pages available in the 
current graphics mode. The length of this array is specified in 
the num_pages field value retrieved by the get_config function; 
the length is also available in the global structure 
config, as element config.mode.num_pages. The fields of the 
PAGE structure are utilized as follows:

BaseAddr	The base address of the video page; that is, the 32-bit GSP 
		memory address of the pixel in the top left corner of the
		monitor screen

DpyStart 	The display start address, which is the address of the first 
		pixel output to refresh the monitor

The BaseAddr and DpyStart fields usually contain identical 
values. The exception occurs in the case of a display system 
utilizing a TMS34070 Color Palette device in either frame-load 
or line-load mode. In a system with a TMS34070, the display 
starting value loaded into the TMS34010's DPYSTRT 
register or into the TMS34020's DPYSTL and DPYSTH 
registers does not correspond to the page's base address; 
they correspond instead to the start of the palette 
information that precedes the page in display memory. 
Note that the palet_inset field retrieved by the get_config 
function (this value is also available in 
the global structure config as element config.mode.palet_inset) 
is specified as the difference between the BaseAddr and 
DpyStart  values given for the page:

		palet_inset = BaseAddr - DpyStart

The array of page information pointed to by global variable page  
is utilized by the set_config and page_flip functions, 
described in Chapter 6.

A.11	PALET Structure Definition

The PALET data structure contains the R-G-B and intensity components
of a particular palette entry. The following is the C typedef 
statement describing the structure:

typedef struct 
{
    unsigned char r;	  /* red component */
    unsigned char g;	  /* green component */
    unsigned char b;	  /* blue component */
    unsigned char i;	  /* intensity component */
} PALET;

The graphics library's global variable DEFAULT_PALET is an 
array of type PALET containing the 16 default palette entries, 
as described in the discussion of the init_palet function in Chapter 6. 
Library global palette is an array of type PALET that contains the 
palette currently in use. The length of this array 
is specified in the palet_size field value retrieved by the get_config 
function; the length is also available in the global structure config, as 
element config.mode.palet_size. For more information on the PALET 
structure, refer to the discussion of the get_palet and set_palet  functions in 

Chapter 6.

A.12	PATTERN Structure Definition

The PATTERN data structure contains information describing an area-fill 
pattern. The following is the C typedef statement describing the structure:

typedef struct 
{
    unsigned short width;   	/* width of pattern */
    unsigned short height;  	/* height of pattern */
    unsigned short depth;   	/* depth (bits/pixel) */
    PTR data;		/* pointer to data */
    int (*hsrv)();	/* horizontal fill routine */
    int (*srv)();	/* general fill routine */
} PATTERN;

The graphics library's global variable pattern is a structure of type PATTERN 
which specifies the current area-fill pattern. The set_patn function accepts as 
its sole argument a pointer to a structure of type PATTERN. (The function uses 
only the first four fields of the PATTERN structure pointed to.) The fields of 
the PATTERN data structure are utilized as follows:
width	Number of pixels per row of pixel array containing pattern

height	Number of rows in pixel array containing pattern

depth	Depth (number of bits per pixel) in pixel array containing pattern

data	Pointer to pixel array containing pattern

hsrv	Pointer to function that renders horizontal lines 
	(sometimes called spans) of regions to be filled with patterns

srv	Pointer to function that renders two-dimensional cells 
	having same width and height as pattern array itself

Currently, patterns are restricted to width 16, height 16, and depth 1. The 
hsrv field points to a routine that is called from assembly language. This 
routine renders a single horizontal line (or span) of a region to be filled, 
and it expects the B-file registers to be set up as they would 
be for a FILL XY instruction. For an example of such a routine, 
refer to the patnline.asm source file in the graphics 
library's \extprims directory.

