Chapter 6 - Core Primitives

This chapter describes the functions in the Core Primitives Library. 
The Extended Primitives Library is described in the next chapter.

Remember to call the set_config function (a member of the Core
Primitives Library) to initialize the drawing environment before
you call any of the other functions in the Core and Extended 
Primitives Libraries.

The table below summarizes the 50 functions in the Core Primitives Library. 
The remainder of this chapter is an alphabetical, detailed description of the 
syntax, usage, and operation of each function. These descriptions are 
augmented by complete example programs that can be compiled 
and run exactly as written.

Function Name	Description

clear_frame_buffer	Clear frame buffer 

clear_page		Clear current drawing page

clear_screen		Clear screen

cpw			Compare point to clipping window

cvxyl			Convert x-y position to linear address

field_extract		Extract field from TMS340
			graphics processor memory

field_insert		Insert field into TMS340
			graphics processor memory

get_colors		Get colors

get_config		Get hardware configuration
			information

get_fontinfo		Get font information

get_modeinfo		Get graphics mode information

get_nearest_color	Get nearest color     

get_offscreen_memory	Get off-screen memory

get_palet 		Get entire palette

get_palet_entry 	Get single palette entry

get_pmask 		Get plane mask

get_ppop		Get pixel processing operation code

get_text_xy		Get text x-y position

get_transp		Get transparency flag

get_vector		Get trap vector

get_windowing		Get window clipping mode

get_wksp		Get workspace information

gsp2gsp 		Transfer from one location
			to another within TMS340
			graphics processor memory

init_palet		Initialize palette

init_text		Initialize text      

lmo			Find leftmost one

page_busy		Get page busy status

page_flip		Flip display and drawing pages 

peek_breg		Peek at B-file register 

poke_breg		Poke value into B-file register 

rmo			Find rightmost one

set_bcolor		Set background color

set_clip_rect		Set clipping rectangle

set_colors		Set foreground and 
			background colors

set_config		Set hardware configuration

set_fcolor		Set foreground color

set_palet 		Set multiple palette entries   

set_palet_entry 	Set single palette entry

set_pmask		Set plane mask

set_ppop		Set pixel processing 
			operation code

set_text_xy		Set text x-y position

set_transp		Set transparency mode

set_vector		Set trap vector

set_windowing		Set window clipping mode

set_wksp		Set workspace information

text_out		Output text

text_outp		Output text at current x-y position

transp_off		Turn transparency off

transp_on 		Turn transparency on

wait_scan 		Wait for scan line

void clear_frame_buffer(color)
unsigned long color; 	/* pixel value */

The clear_frame_buffer  function rapidly clears the entire display memory by 
setting it to the specified color. If the display memory contains multiple 
display pages (for example, for double-buffered animation) all pages are 
cleared.

Argument color  is a pixel value. Given a screen pixel depth of N bits, the 
pixel value contained in the N LSBs of the argument is replicated throughout 
the display memory. In other words, the pixel value is replicated 32/N times 
within each 32-bit longword in the display memory. Pixel size N is restricted 
to the values 1, 2, 4, 8, 16, and 32 bits.

If the value of argument color is specified as -1, the function clears the 
display memory to the current background color. (In order to clear the frame 
buffer to all 1s when the pixel size is 32 bits, set the background color to 
0xFFFFFFFF and call the clear_frame_buffer function with an argument of -1.)

This function can rapidly clear the screen in hardware configurations that 
support bulk initialization of the display memory. Bulk initialization is 
supported by video RAMs that can perform serial-register-to-memory cycles. 
The serial register in each video RAM is loaded with initialization data and
copied internally to a series of rows in the memory array. Whether the function 
utilizes bulk initialization or some other functionally equivalent method of 
clearing the screen varies from one implementation to the next.

Off-screen areas of the display memory may also be affected by this function; 
data stored in such areas may be lost as a result. The clear_screen function is 
similar in operation but does not affect data contained in off-screen areas.

If the graphics display system reserves an area of the display memory to store 
palette information (as is the case in configurations that use the TMS34070 
color palette chip), this area is left intact by the function.

Use the clear_frame_buffer function to clear the display memory to the default 
background color. Use the text_out function to print a couple of words to the 
screen.

main()
{
    set_config(0, !0);
    clear_frame_buffer(-1);
    text_out(10, 10, "Hello world.");
}

void clear_page(color)
unsigned long color;	/* pixel value */

The clear_page function rapidly clears the entire drawing page by setting it to 
the specified pixel value. If the display memory contains multiple display 
pages (for example, for double-buffered animation), only the current drawing 
page is cleared.

Given a screen pixel depth of N bits, the pixel value contained in the N LSBs 
of argument color is replicated throughout the drawing page. In other words, 
the pixel value is replicated 32/N times within each 32-bit longword in the 
page. Pixel size N is restricted to the values 1, 2, 4, 8, 16, and 32 bits.

If the value of argument color is specified as -1, the function clears the page 
to the current background color. (In order to clear the frame buffer to all 1s 
when the pixel size is 32 bits, set the background color  to 0xFFFFFFFF and 
call the clear_frame_buffer function with an argument of -1.)

This function can rapidly clear the screen in hardware configurations that 
support bulk initialization of the display memory. Bulk initialization is 
supported by video RAMs that can perform serial-register-to-memory cycles.
The serial register in each video RAM is loaded with initialization data and 
copied internally to a series of rows in the memory array. Whether the function 
utilizes bulk initialization or some other functionally equivalent method of 
clearing the screen varies from one implementation to the next.

The clear_page function can affect off-screen as well as on-screen areas of the 
display memory. Data stored in off-screen areas may be lost as a result. The 
clear_screen function is similar in operation but does not affect data 
contained in off-screen areas. The clear_page function may clear the screen 
more rapidly than the clear_screen function, depending on the implementation.

If the graphics display system reserves an area of the display memory to store 
palette information (as is the case in configurations that use the TMS34070 
color palette chip), this area is left intact by the function.

Use the clear_page function to clear alternating drawing pages in an 
application requiring double-buffered animation. The graphics mode
selected by the set_config function is assumed to support more than 
one video page. The text_out function is used to make the letters 
abc rotate in a clockwise direction around the digits 123.

#define  GMODE	0	/* double-buffered graphics mode */
#define  RADIUS   64	/* radius of rotating text */

main()
{
    long x, y;
    short disppage, drawpage;

    set_config(GMODE, !0);
    drawpage = 0;
    disppage = 1;
    x = RADIUS << 16;
    y = 0;
    for ( ; ; ) {
	page_flip(disppage ^= 1, drawpage ^= 1);
	x -= y >> 5;
	y += x >> 5;
	while (page_busy())
	    ;
	clear_page(-1);
	text_out(RADIUS, RADIUS, "123");
	text_out(RADIUS+(x>>16), RADIUS+(y>>16), "abc");
    }
}

void clear_screen(color)
unsigned long color;	/* pixel value */

The clear_screen function clears the entire current drawing page by setting it 
to the specified pixel value. If the display memory contains multiple display 
pages (for example, for double-buffered animation), only the current 
drawing page is cleared.

Given a screen pixel depth of N bits, the pixel value contained in the N LSBs 
of argument color is replicated throughout the drawing page. In other words, 
the pixel value is replicated 32/N times within each 32-bit longword in the 
area of display memory corresponding to the page. Pixel size N is restricted to 
the values 1, 2, 4, 8, 16, and 32 bits.

If the value of argument color is specified as -1, the function clears the page 
to the current background color. (In order to clear the frame buffer to all 1s 
when the pixel size is 32 bits, set the background color to 0xFFFFFFFF and 
call the clear_frame_buffer function with an argument of -1.)

The clear_screen function does not affect data contained in off-screen areas of 
the display memory. The clear_page function is similar in operation but may 
affect data contained in off-screen areas; data stored in such areas may be 
lost as a result. The clear_page function may clear the screen more rapidly 
than the clear_screen function, depending on the implementation.

Use the clear_screen function to clear the screen to the default background 
color prior to printing the text "Hello world." on the screen.

main()
{
    set_config(0, !0);
    clear_screen(-1);
    text_out(10, 10, "Hello world.");
}

short cpw(x, y)
short x, y;	/* pixel coordinates */

The cpw function returns a 4-bit outcode indicating the specified pixel's 
position relative to the current clipping window. The outcode indicates 
whether the pixel is located above or below, to the left or right of, or
inside the window.

Arguments x and y are the coordinates of the pixel, specified relative to
the current drawing origin.

The clipping window is rectangular. As shown in Figure 6-1, the 
area surrounding the clipping window is partitioned into 8 regions. 

Figure 6-1.	Outcodes for Line Endpoints

Each of the 8 regions is identified by a unique 4-bit outcode. The 
outcode values for the 8 regions and for the window itself are
encoded as follows:

01XX2	if the point lies above the window

10XX2	if the point lies below the window

XX012	if the point lies left of the window

XX102	if the point lies right of the window

00002	if the point lies within the window

The outcode is right-justified in the 4 LSBs of the return value and 
zero-extended.

Refer to the user's guide for the TMS34010 or TMS34020 for a detailed 
description of the outcodes.

Use the cpw function to animate a moving object that bounces off the sides of 
the clipping window. When a check of the object's x-y coordinates indicates 
that it has strayed outside the window, the sign of the object's x or y 
component of velocity, as appropriate, is reversed. The moving object is an 
asterisk rendered in the system font. The asterisk is erased by overwriting 
it with a blank. Note that the system font is a block font; overwriting an 
asterisk with a blank from a proportionally spaced font might not
have the same effect.

#define  WCLIP	 130	/* width of clipping window */
#define  HCLIP	 100	/* height of clipping window */

main()
{
    short x, y, vx, vy;

    set_config(0, !0);
    clear_screen(-1);
    set_clip_rect(WCLIP, HCLIP, 0, 0);
    vx = 2;
    vy = 1;
    for (x = y = 0; ; x += vx, y += vy) {
	text_out(x, y, "*");
	if (cpw(x, 0))
	    vx = -vx;
	if (cpw(0, y))
	    vy = -vy;
	wait_scan(HCLIP);
	text_out(x, y, " ");
    }
}

typedef unsigned long PTR;  	/* 32-bit GSP memory address */

PTR cvxyl(x, y)
short x, y;	/* x-y coordinates */

The cvxyl function returns the 32-bit address of a pixel in the TMS340
graphics processor's memory, given the x and y coordinates
of the pixel on the screen.

Arguments x and y are the coordinates of the specified pixel, defined 
relative to the current drawing origin. If the coordinates correspond 
to an off-screen location, the calling program is responsible for
ensuring that the coordinates correspond to a valid pixel location.

Use the cvxyl function to determine the base addresses of the all the 
video pages available in graphics mode 0. The page_flip function is 
used repeatedly to flip to a new page before the cvxyl function is called. 
The text_out function is used to print out the 32-bit memory address 
of each page.

#include  <gsptypes.h>

main()
{
    short x, y, n, digit;
    long p;
    char *s, c[80];
    CONFIG cfg;
    FONTINFO fntinf;

    set_config(0, 1);
    clear_screen(-1);
    get_config(&cfg);
    get_fontinfo(-1, &fntinf);
    x = y = 10;
    text_out(x, y, "video page addresses:");
    for (n = 0; n < cfg.mode.num_pages; n++) {
	page_flip(0, n);
	s = &c[strlen(strcpy(c,  "  0x00000000"))];
	for (p = cvxyl(0, 0); p; p /= 16) {
		digit = p & 15;
		*--s = (digit < 10) ? (digit + '0') : (digit + 'A' - 10);
	}
	y += fntinf.charhigh;
	page_flip(0, 0);
	text_out(x, y, c);
    }
}

typedef unsigned long PTR;	/* 32-bit GSP memory address */

unsigned long field_extract(gptr, fs)
PTR gptr;              	/* GSP memory pointer */
unsigned short fs;      	/* field size */

The field_extract function returns the contents of a field located in memory.

Argument gptr is a pointer containing the 32-bit address of a field in the 
TMS340 graphics processor's memory. Argument fs specifies
the length of the field and is restricted to values in the range 1 to 32 bits.

The function definition places no restrictions on the alignment of the address; 
the field is permitted to begin at any bit address. Given an fs value of
N and a gptr value of A, the specified field consists of contiguous bits
A through A+N-1 in memory.

The contents of the field are placed in the N LSBs of the return value and 
zero-extended.

Use the field_extract function to examine a field from an I/O register 
located in the TMS340 graphics processor's memory. Retrieve
the contents of the PPOP field, a 5-bit field that begins in bit 10
of the CONTROL register.

#define  CONTROL   0xC00000B0 /* address of GSP CONTROL reg. */
#define  XOR	   10   /* PPOP = XOR */

main()
{
    unsigned long ppop;
    static char c[] = "PPOP = ????";

    set_config(0, !0);
    clear_screen(-1);
    set_ppop(XOR);	    	/* load PPOP field */
    ppop = field_extract(CONTROL+10, 5);	/* read it back */
    ltoa(ppop, &c[7]);
    text_out(10, 10, c);
}

typedef unsigned long PTR;	/* 32-bit GSP memory address */

void field_insert(gptr, fs, val)
PTR gptr;	/* GSP memory pointer */
short fs;	/* field size */
unsigned long val;	/* data to be inserted */

The field_insert function writes a specified value to a field located
in the TMS340 graphics processor's memory.

Argument gptr is a pointer containing the 32-bit address of a field in the 
TMS340 graphics processor's memory. Argument fs specifies the length
of the field and is restricted to values in the range 1 to 32 bits. 
Argument val specifies the value to be written.

The function definition places no restrictions on the alignment of the address; 
the field is permitted to begin at any bit address. Given an fs value of N, and 
a gptr value of A, the specified field consists of contiguous bits A through 
A+N-1 in memory. The N LSBs of argument val are copied into the
specified field in memory; the remaining bits of the argument 
are ignored by the function.

Use the field_insert  function to load a value into a field in an I/O register 
located in the TMS340 graphics processor's memory. The PPOP field is a 
5-bit field that begins in bit 10 of the CONTROL register. Use the
get_ppop function to read back the PPOP field, and use the
text_out  function to print its value.

#define  CONTROL   0xC00000B0	/* I/O register address */
#define  NOT_OR    13		/* NOT src OR dst --> dst */

main()
{
    static char c[] = "PPOP = ????";

    set_config(0, !0);
    clear_screen(-1);
    field_insert(CONTROL+10, 5, NOT_OR);   	/* load PPOP field */
    ltoa(get_ppop(), &c[7]);	/* read it back */
    text_out(10, 10, c);
}

void get_colors(fcolor, bcolor)
unsigned long *fcolor;	/* pointer to foreground color */
unsinged long *bcolor;	/* pointer to background color */

The get_colors function retrieves the pixel values corresponding to the
current foreground and background colors.

Arguments fcolor and bcolor are pointers to long integers into which the 
function loads the foreground and background colors, respectively. 
Each pixel value is right-justified within its destination longword 
and zero-extended.

Use the get_colors function to retrieve the default foreground and
background pixel values assigned by the set_config function. 
Use the text_out function to print the values on the screen.

#include <gsptypes.h>	    	/* defines FONTINFO structure */

static FONTINFO fontinfo;

main()
{
    unsigned long fcolor, bcolor;
    short x, y;
    static char c1[40] = "white = ", c2[40] = "black = ";

    set_config(0, !0);
    clear_screen(-1);
    get_fontinfo(0, &fontinfo);
    get_colors(&fcolor, &bcolor);	/* retrieve colors */
    ltoa(fcolor, &c1[8]);
    x = y = 10;
    text_out(x, y, c1);
    ltoa(bcolor, &c2[8]);
    y += fontinfo.charhigh;
    text_out(x, y, c2);
}

typedef 	struct
{
	long 	disp_pitch;
	short 	disp_vres;
	short 	disp_hres
	short 	screen_wide
	short 	screen_high;
	short 	disp_psize;
	long 	pixel_mask;
	short 	palet_gun_depth;
	long 	palet_size;
	short 	palet_inset;
	short 	num_pages;
	short	num_offscrn_areas;
	long 	wksp_addr;
	long 	wksp_pitch;
} MODEINFO;

typedef 	struct
{
	short 	version_number;
	long 	comm_buff_size;
	long 	sys_flags;
	long 	device_rev;
	short 	num_modes;
	short 	current_mode;
	long 	program_mem_start;
	long 	program_mem_end;
	long 	display_mem_start;
	long 	display_mem_end;
	long 	stack_size;
	long 	shared_mem_size;
	HPTR 	shared_host_addr;
	PTR 	shared_gsp_addr;
	MODEINFO mode;
} CONFIG;

void get_config(config)
CONFIG *config;	/* hardware configuration info */

The get_config function retrieves a list of parameters that describe 
the characteristics of both the hardware configuration and 
the current graphics mode.

Argument config is a pointer to a structure of type CONFIG, into which
the function copies parameter values describing the configuration
of the display hardware.  The last field in the  CONFIG  structure
is a structure of  type  MODEINFO, which contains parameters describing
the currently selected graphics mode.

The fields of the CONFIG structure are defined as follows:

version_number	TIGA revision number, assigned 
		by Texas Instruments Incorporated.

comm_buff_size	Size, in bytes, of the TIGA communications
 		buffer. The contents of this field are undefined 
		in TMS340 Graphics Library applications.

sys_flags	Bits 0-7 indicate which of up to 8 TMS34082
		Floating-Point Coprocessors are present in the
		system. Bits 8-15 are reserved.

device_rev	This is the TMS340 graphics processor
		silicon revision number, as generated by the
		processor's REV instruction.

num_modes	Number of graphics modes for boards
		that allow the switching between different 
		display setups.

current_mode	Mode number corresponding 
		to the current graphics mode.

program_mem_start  Start address of program memory.

program_mem_end    End address of program memory.

display_mem_start  Start address of display memory.

display_mem_end	End address of display memory.

stack_size	Size in bytes of the block of memory allocated
		for both the system stack and program stack. 
		The two stacks grow toward each other from 
		opposite ends of the block.

shared_mem_size	Size in bytes of dual-ported memory that is 
		shared between the host processor and the
		TMS340 graphics processor.

shared_host_addr  If shared_mem_size is nonzero, this is the start
		address in host memory of the shared memory; 
		otherwise, it is undefined.

shared_gsp_addr	If shared_mem_size is nonzero, this is the 
		start address in TMS340 graphics processor
		memory of the shared memory; otherwise, it is 
		undefined.

The fields of the MODEINFO structure are defined as follows:

disp_pitch	The display pitch is the difference in memory
		addresses of two vertically adjacent 
		pixels on the screen.

disp_vres	The display vertical resolution is the number
		of scan lines on the screen.

disp_hres	The display horizontal resolution is the number
		of  pixels per scan line on the screen.

screen_wide	The width of the active screen in millimeters.
		In systems in which this dimension is unknown, 
		set to 0.

screen_high	The height of the active screen in millimeters.
		In systems in which this dimension is unknown, 
		set to 0.

disp_psize	Pixel size (in bits).

pixel_mask	Contains a mask of the active bits within a pixel.
		Pixel sizes are restricted to powers of 2 in the range 1 to
	 	32. Not all bits within each pixel are necessarily used, 
		however.  For example,  if  the  pixel  size  is  8  bits, 
		but only   the  video  RAM  sockets  corresponding 
		to  the  6 LSBs of  each  pixel are actually  populated, 
		pixel_mask is set to 0x3F.

palet_gun_depth	Number of bits per gun in the color palette.

palet_size	Number of entries in the color palette.

palet_inset	For most systems, this field is set to 0.
		For TMS34070-based boards, which store the palette 
		in the frame buffer, this field contains the 
		length in bits of the palette data that precedes the 
		pixel data for each scan line.

num_pages	Number of video pages (or frame buffers) in
		display memory.  Some systems provide multiple
		pages to support flickerless animation.

num_offscrn_areas  This is the number of off-screen memory blocks
		available.  This field specifies the number 
		of two-dimensional  pixel  arrays  available  
		in  off-screen  portions of  the  display  memory.  
		(See  description  of  get_offscreen_memory function.)

wksp_addr	 Starting linear address in memory of the
		off-screen workspace area, which is 1 bit per pixel
		but has the same horizontal and vertical 
		dimensions as the screen.

wksp_pitch	Pitch of  off-screen workspace area.  If 0,
		then no off-screen workspace is currently allocated.

Note that the structures described above may change in subsequent revisions. To 
minimize the impact of such changes, 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 will be updated in future revisions to track any such changes in data 
structure definitions.

Use the get_config function to retrieve the pixel size for the current graphics 
mode. Use the text_out function to print the pixel size on the screen.

#include <gsptypes.h>	    	/* defines CONFIG structure */

main()
{
    CONFIG cfg;
    unsigned long psize;
    static char c[] = "pixel size = ????";

    set_config(0, !0);
    clear_screen(-1);
    get_config(&cfg);
    psize = cfg.mode.disp_psize; 	/* pixel size in bits */
    ltoa(psize, &c[13]);
    text_out(10, 10, c);
}

typedef struct
{
    char facename[30];
    short deflt;
    short first;
    short last;
    short maxwide;
    short avgwide;
    short maxkern;
    short charwide;
    short charhigh;
    short ascent;
    short descent;
    short leading;
    FONT *fontptr;
    short id;
} FONTINFO;

short get_fontinfo(id, pfontinfo)
short id;	/* font identifier */
FONTINFO *pfontinfo;	/* font information */

The get_fontinfo function copies a structure whose elements describe the 
characteristics of the designated font. The font must have been previously 
installed in the font table.

Argument id is an index that identifies the font. The system font is always 
designated as font 0; that is, it is identified by an id value of 0. The system 
font is installed in the font table during initialization of the drawing 
environment by the set_config function. Additional fonts may be installed in 
the font table by means of calls to the install_font function. The install_font 
function returns an identifier value that is subsequently used to refer to the 
font. The currently selected font is designated by an id value of -1.

Argument pfontinfo is a pointer to a structure of type FONTINFO, 
into which the function copies parameter values that characterize 
the font designated by argument id.

The function returns a nonzero value if the structure is successfully copied; 
otherwise, 0 is returned.

The fields of the FONTINFO structure are defined as follows:

facename	String containing font name.

deflt	       ASCII code of default character.

first	       ASCII code of first character implemented in font.

last	       ASCII code of last character implemented in font.

maxwide 	Maximum character width.

avgwide 	Average width of characters.

maxkern 	Maximum character kerning amount.

charwide	Width of characters (0 in the case of a 
		proportionally spaced font).

charhigh	Character height (sum of ascent, descent, and leading).

ascent		Ascent (distance in pixels from base line
		to top of highest character).

descent 	Descent (distance in pixels from base line
		to bottom of lowest descender).

leading 	Leading (vertical spacing in pixels from
		bottom of one line of text to top of next line of text).

fontptr 	Address of font in TMS340 graphics
		processor's memory.

id	       Font identifier (font table index).

Note that the structure described above may change in subsequent 
revisions. To minimize the impact of such changes, 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 will be updated in future
revisions to track any such changes in data structure definitions.

Use the get_fontinfo function to retrieve the face name, character width, 
and character height of the system font.  Use the text_out function
to print the three font parameters on the screen.

#include <gsptypes.h>	    /* defines FONTINFO structure */

main()
{
    FONTINFO fntinf;
    short x, y;
    char c[80];

    set_config(0, !0);
    clear_screen(-1);
    get_fontinfo(0, &fntinf);
    x = y = 10;
    text_out(x, y, fntinf.facename);
    y += fntinf.charhigh;
    strcpy(c, "character width = ");
    ltoa(fntinf.charwide, &c[18]);
    text_out(x, y, c);
    y += fntinf.charhigh;
    strcpy(c, "character height = ");
    ltoa(fntinf.charhigh, &c[19]);
    text_out(x, y, c);
}

short get_modeinfo(index, modeinfo)
short index;	/* graphics mode index */
MODEINFO *modeinfo;	/* graphics mode information */

The get_modeinfo function copies a structure whose elements 
describe the characteristics of the designated graphics mode.

Argument index is a number that identifies one of the graphics modes 
supported by the display hardware configuration. The index values are 
assigned to the available graphics modes by the display hardware 
vendor. Each configuration supports one or more graphics modes, 
which are numbered in ascending order beginning with 0.

Argument modeinfo is a pointer to a structure of type MODEINFO, 
into which the function copies parameter values that 
characterize the graphics mode designated by argument index.

The function returns a nonzero value if the mode information 
is successfully retrieved. If an invalid index is specified, 
the function returns 0.

The number of graphics modes supported by a particular display 
configuration is specified in the num_modes field of the CONFIG 
structure returned by the get_config function. Given that the number 
of supported modes is some number N, 
the modes are assigned indices from 0 to N-1.

The get_modeinfo function has no effect on the current graphics 
mode setting.  The display is configured in a particular graphics 
mode by means of a call to the set_config function.

The fields of the MODEINFO structure are defined as follows:

disp_pitch	The display pitch is the difference in memory 
		addresses of two vertically adjacent pixels
		on the screen.

disp_vres	The display vertical resolution is the number of 
		scan lines on	the screen.

disp_hres	The display horizontal resolution is the 
		number of pixels per scan line on the screen.

screen_wide	The width of the active screen in millimeters. 
		In systems in which this dimension is unknown,
		set to 0.

screen_high	The height of the active screen in millimeters. 
		In systems in which this dimension is unknown,
		set to 0.

disp_psize	Pixel size (in bits).

pixel_mask	Contains a mask of the active bits within a pixel. 
		Pixel sizes are restricted to powers of 2 in the
		range 1 to 32. Not all bits within each pixel are
		necessarily used,  however. For example, if the pixel
		size is 8 bits, but only the video RAM sockets
		corresponding to the 6 LSBs of
		each pixel are actually populated,
		the pixel_mask is set to 0x3F.

palet_gun_depth	Number of bits per gun in the color palette.

palet_size	Number of entries in the color palette.

palet_inset	For most systems, this field is set to 0. 
		For TMS34070-based boards, which store
		the palette in the frame buffer, this field contains the
		length in bits of the palette data that precedes
		the pixel data for each scan line.

num_pages	Number of display pages in display memory.  
		Some systems provide multiple pages
		to support flickerless animation.

num_offscrn_areas	This is the number of off-screen
		memory blocks available.  This  
		field  specifies   the   number  
		of  two-dimensional  pixel  arrays  
		available in  off-screen  portions  
		of the display memory.  (See description 
		of  get_offscreen_memory function).

wksp_addr	Starting linear address in memory of 
		the off-screen workspace area, which
		is 1 bit per pixel but has the same horizontal and
		vertical dimensions as the screen.

wksp_pitch	Pitch of off-screen workspace area. 
		If 0, then no off-screen
		workspace is currently allocated.

Note that the structures described above may change in 
subsequent revisions. To minimize the impact of such
changes, 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 will be updated in future revisions
to track any such changes in data structure definitions.

Use the get_modeinfo function to retrieve a list of the screen 
resolutions corresponding to the graphics modes supported
by the display hardware configuration. Use the text_out function
to print the list on the screen.

#include <gsptypes.h>	    /* MODEINFO, CONFIG and FONTINFO */

main()
{
    MODEINFO modinf;
    CONFIG cfg;
    FONTINFO fntinf;
    char c[80];
    short x, y, mode, i;

    set_config(0, !0);
    clear_screen(-1);
    get_config(&cfg);
    get_fontinfo(0, &fntinf);
    x = y = 10;
    for (mode = 0; get_modeinfo(mode, &modinf); mode++) {
   	i = strlen(strcpy(c, "mode "));
	i += ltoa(mode, &c[i]);
	strcpy(&c[i], ":  ");
	i = strlen(c);
	i += ltoa(modinf.disp_hres, &c[i]);
	strcpy(&c[i], "-by-");
	i = strlen(c);
	ltoa(modinf.disp_vres, &c[i]);
	text_out(x, y, c);
	y += fntinf.charhigh;
    }
}

unsigned long get_nearest_color(r, g, b, i)
unsigned char r, g, b;	/* red, green and blue components */
unsigned char i;	/* gray-scale intensity */

The get_nearest_color  function searches the current palette and 
returns the pixel value whose color is closest to that specified by 
the input arguments.

If the current graphics mode supports a color display, 
arguments r, g, and b represent the 8-bit red, green, and blue 
components of the target color. Each component value 
corresponds to an intensity value in the range 0 to 255, where 
255 is the brightest intensity and 0 is the darkest.

In the case of a gray-scale display, argument  i  represents a 
gray-scale intensity in the range 0 to 255.

The pixel value returned by the function is right-justified 
and zero-extended.

In the case of a gray-scale palette, the return value is the palette
index value whose intensity is closest to that specified in argument i.

In the case of a color palette, the function performs a more complex 
calculation. The function calculates the magnitude of the differences 
between the r, g, and b argument values and the red, green, and blue 
components, respectively, of each individual color available in the 
palette. Each of the three differences (red, green, and blue) is multiplied 
by an individual weighting factor, and the sum of the weighted 
differences is treated as the effective distance of the color palette entry
from the color specified by arguments r, g, and b. The palette entry 
corresponding to the smallest weighted sum is selected as being
nearest to the specified color. The function returns 
the palette index value corresponding to the selected color.

Use the get_nearest_color  function to determine the pixel 
values around the perimeter of a color wheel. Use the fill_piearc 
function from the Extended Primitives Library to render the wheel. 
The wheel is partitioned into the following six regions
of color transition:

1)	 red to yellow

2)	 yellow to green

3)	 green to cyan

4)	 cyan to blue

5)	 blue to magenta

6)	 magenta to red

Each region spans a 60-degree arc of the wheel.

color_wheel(t, r, g, b, i)
short t;
unsigned char r, g, b, i;
{
    long val;

    val = get_nearest_color(r, g, b, i);
    set_fcolor(val);
    fill_piearc(140, 110, 10, 10, t, 1);
}

main()
{
    short t;
    unsigned char r, g, b;

    set_config(0, !0);
    clear_screen(-1);
    for (t = 0, r = 255, g = b = 15; t < 60; t++, g += 4)
	color_wheel(t, r, g, b, g); 	/* red to yellow */
    for ( ; t < 120; t++, r -= 4)
	color_wheel(t, r, g, b, r);	/* yellow to green */
    for ( ; t < 180; t++, b += 4)
	color_wheel(t, r, g, b, b);	/* green to cyan */
    for ( ; t < 240; t++, g -= 4)
	color_wheel(t, r, g, b, g);	/* cyan to blue */
    for ( ; t < 300; t++, r += 4)
	color_wheel(t, r, g, b, r);	/* blue to magenta */
    for ( ; t < 360; t++, b -= 4)
	color_wheel(t, r, g, b, b);	/* magenta to red */
}

typedef unsigned long PTR; 	/* 32-bit GSP memory address */

typedef struct {
    PTR addr;
    unsigned short xext, yext;
} OFFSCREEN_AREA;

void get_offscreen_memory(num_blocks, offscreen)
short num_blocks;		/* number of off-screen buffers */
OFFSCREEN_AREA *offscreen;	/* list of off-screen buffers */

The get_offscreen_memory function returns a list of off-screen
buffers located in the TMS340 graphics processor's display memory.

Argument num_blocks specifies the number of off-screen buffer areas 
to be listed.  Argument  offscreen  is  an  array  to contain the
list of off-screen  buffers.  Each  element  of  the  offscreen  array 
is  a  structure  of  type  OFFSCREEN_AREA.

The fields of the OFFSCREEN_AREA structure are defined as follows:

addr	base address of off-screen buffer

xext	x extent (width in pixels) of off-screen buffer

yext	y extent (height in pixels) of off-screen buffer

An off-screen buffer is a two-dimensional array of pixels, the 
rows of which may not be contiguous in memory. 
The pixel size is the same as that of the screen, and each
off-screen buffer has the same pitch as the screen. The pitch 
is the difference in memory addresses between two vertically 
adjacent pixels in the buffer.

If an off-screen buffer is used as the off-screen workspace (see the 
description of the set_wksp and get_wksp functions), this buffer 
is always the first buffer listed in the offscreen array.

Let N represent the number of off-screen buffers available in a
particular graphics mode. If argument num_blocks is greater than N, 
only the first N elements of the offscreen array will be loaded
with valid data. If argument num_blocks  is  less  than N, only the
first  num_blocks  elements of  the  offscreen array will be loaded
with valid data. The number of off-screen areas available in 
the current mode is specified in the num_offscrn_areas field of 
the CONFIG structure returned by the get_config function.

After the display memory (usually video RAM) has been
partitioned into one or more video pages (or frame buffers), 
some number of rectangular, noncontiguous blocks of display
memory are typically left over. These blocks may not be 
suitable for general use (for example, for storing a program) 
but may be of use to some applications as temporary storage
for graphical information such as the areas behind pull-down
menus on the screen. 

Use the get_offscreen_memory function to list the first (up to)
5 off-screen buffers available in the current graphics mode. 
Use the text_out function to print the x and y extents 
of each buffer on the screen.

#include <gsptypes.h>	/* OFFSCREEN_AREA, CONFIG, FONTINFO */
#define   MAXBUFS     5 	/* max. number of buffers needed */

main()
{
    OFFSCREEN_AREA offscrn[MAXBUFS];
    CONFIG cfg;
    FONTINFO fntinf;
    short x, y, i, k, nbufs;
    char c[80];

    set_config(0, !0);
    clear_screen(-1);
    get_config(&cfg);
    get_fontinfo(-1, &fntinf);
    if ((nbufs = cfg.mode.num_offscrn_areas) > MAXBUFS)
	nbufs = MAXBUFS;
    get_offscreen_memory(nbufs, offscrn);
    if (!nbufs)
	text_out(10, 10, "No off-screen buffers available.");
    else
	for (i = 0, x = y = 10; i < nbufs; i++) {
	    k = strlen(strcpy(c, "Buffer "));
	    k += ltoa(i, &c[k]);
	    k += strlen(strcpy(&c[k], ":  xext = "));
	    k += ltoa(offscrn[i].xext, &c[k]);
	    k += strlen(strcpy(&c[k], ", yext = "));
	    ltoa(offscrn[i].yext, &c[k]);
	    text_out(x, y, c);
	    y += fntinf.charhigh;
	}
}

typedef struct { unsigned char r, g, b, i; } PALET;

void get_palet(palet_size, palet)
short palet_size;	/* number of palette entries */
PALET *palet;	/* list of palette entries */

The get_palet function copies multiple palette entries into an array.

Argument palet_size is the number of palette entries 
to load into the target array.

Argument palet  is an array of type PALET. Each array element 
is a structure containing r, g, b, and i fields. Each field specifies 
an 8-bit red, green, blue, or gray-scale intensity value in the range
0 to 255, where 255 is the brightest intensity and 0 is the darkest. 
In the case of a graphics mode for a color display, the red, green, and
blue component intensities are loaded into the r, g, and b fields, 
respectively, while the i field is set to 0. In the case of a gray-scale
mode, the intensities are loaded into the i fields, and 
the r, g, and b fields are set to 0.

If argument palet_size specifies some number N that is less than the 
number of entries in the palette, only the first N palet entries are 
loaded into the array. If the number N of palette entries is less 
than the number specified in palet_size, only the first N elements 
of the array are modified. The number of palette entries in the
current graphics mode is specified in the palet_size 
field of the CONFIG structure returned by the get_config function.

The 8-bit r, g, b, and i values retrieved for each palette entry 
represent the color components or gray-scale intensity actually 
output by the physical display device. For example, assume
that the r, g, b, and i values of a particular palette entry are set by
the set_palet or set_palet_entry functions to the following values:  
r = 0xFF, g = 0xFF, b = 0xFF, and i = 0. If the 
display hardware supports only 4 bits of red, green, and blue
intensity per gun, the values read by a call to get_palet 
or get_palet_entry are:  r = 0xF0, g = 0xF0, b = 0xF0, and i = 0.

Use the get_palet function to get the r, g, b, and i components 
of the first 8 colors in the default palette. Use the text_out function
to print the values on the screen.

#include <gsptypes.h>	 /* PALET, CONFIG and FONTINFO */
#define  MAXSIZE   8	 /* max. number of LUT entries to print */

main()
{
    PALET lut[16];
    CONFIG cfg;
    FONTINFO fntinf;
    short k, n, size, x, y;
    char *s, c[80];

    set_config(0, !0);
    clear_screen(-1);
    get_config(&cfg);
    if ((size = cfg.mode.palet_size) > MAXSIZE)
	size = MAXSIZE;
    get_palet(size, lut);   /* get up to 8 palette entries */
    get_fontinfo(-1, &fntinf);
    x = y = 10;
    for (k = 0; k < size; k++, y += fntinf.charhigh) {
	n = strlen(strcpy(c, "color "));
	n += ltoa(k, &c[n]);
	n += strlen(strcpy(&c[n], ": r="));
	n += ltoa(lut[k].r, &c[n]);
	n += strlen(strcpy(&c[n], ", g="));
	n += ltoa(lut[k].g, &c[n]);
	n += strlen(strcpy(&c[n], ", b="));
	n += ltoa(lut[k].b, &c[n]);
	n += strlen(strcpy(&c[n], ", i="));
	n += ltoa(lut[k].i, &c[n]);
	text_out(x, y, c);
    }
}

short get_palet_entry(index, r, g, b, i)
long index;		       /* index to palette entry */
unsigned char *r, *g, *b;      /*red, green and blue components*/
unsigned char *i;	       /* gray-scale intensity */

The get_palet_entry routine returns the red, green, blue, and gray-scale 
intensity components of a specified entry in the palette.

The palette entry is specified by argument index, which is an index 
into the color look-up table, or palette. If the palette contains 
N entries, valid indices are in the range 0 to N-1. The number
of palette entries in the current graphics mode is specified in the 
palet_size field of the CONFIG structure 
returned by the get_config function.

Arguments r, g, b, and i are pointers to the red, green, blue, 
and gray-scale intensity values, respectively, that are
retrieved by the function. Each intensity is represented as 
an 8-bit value in the range 0 to 255, where 255 is 
the brightest intensity and 0 is the darkest. In the case of a
graphics mode for a color display, the red, green, and 
blue component intensities are loaded 
into the r, g, and b fields, respectively, while the i field is set
to 0. In the case of a gray-scale mode, the intensity is 
loaded into the i field, and the r, g, and b fields are set to 0.

If argument index is in the valid range, the function returns 
a nonzero value, indicating that the components of the 
palette entry have been successfully 
retrieved. If argument index is invalid, the return value is 0, 
indicating that no palette entry corresponds to the
specified index.

Use the get_palet_entry function to get the r, g, b, and i 
components of the first 8 colors in the default palette. 
Use the text_out function to print the values on the screen.

#include <gsptypes.h>	 /* CONFIG and FONTINFO struct's */
#define  MAXSIZE   8	 /* max. number of LUT entries to print */

main()
{
    CONFIG cfg;
    FONTINFO fntinf;
    long k, size;
    unsigned char r, g, b, i;
    short n, x, y;
    char *s, c[80];

    set_config(0, !0);
    clear_screen(-1);
    get_config(&cfg);
    if ((size = cfg.mode.palet_size) > MAXSIZE)
	size = MAXSIZE;
    get_fontinfo(-1, &fntinf);
    x = y = 10;
    for (k = 0; k < size; k++, y += fntinf.charhigh) {
	get_palet_entry(k, &r, &g, &b, &i);
	n = strlen(strcpy(c, "color "));
	n += ltoa(k, &c[n]);
	n += strlen(strcpy(&c[n], ": r="));
	n += ltoa(r, &c[n]);
	n += strlen(strcpy(&c[n], ", g="));
	n += ltoa(g, &c[n]);
	n += strlen(strcpy(&c[n], ", b="));
	n += ltoa(b, &c[n]);
	n += strlen(strcpy(&c[n], ", i="));
	n += ltoa(i, &c[n]);
	text_out(x, y, c);
    }
}

unsigned long get_pmask()

The get_pmask function returns the value of the plane mask. 
The size of the plane mask in bits is the same as the pixel size.

Given a pixel size of N bits, the plane mask is right-justified in 
the N LSBs of the return value and zero-extended. 
The screen pixel size in the current graphics mode is specified
in the disp_psize field of the CONFIG structure 
returned by the get_config function.

The plane mask designates which bits within a pixel are 
protected against writes and affects all operations on pixels. 
During writes, the 1s in the plane mask designate bits in the
destination pixel that are protected against 
modification, while the 0s in the plane mask designate bits
that can be altered. During reads, the 1s in the plane mask 
designate bits in the source pixel that are read as 0s, while
the 0s in the plane mask designate bits that 
can be read from the source pixel as is.

The plane mask is set to its default value of 0 during 
initialization of the drawing environment by the set_config
function. The plane mask can be altered 
with a call to the set_pmask function.

The plane mask corresponds to the contents of the 
TMS340 graphics processor's PMASK register. The effect 
of the plane mask in conjunction with the 
pixel-processing operation and the transparency mode is 
described in the user's guides for the TMS34010 
and TMS34020.

Use the get_pmask function to verify that the 
plane mask is initialized to 0 by a call to the
set_config function. Use the text_out  function to
print the default plane mask value to the screen.

main()
{
    unsigned long pmask;
    short digit;
    char *s1, *s2;

    set_config(0, !0);
    clear_screen(-1);
    s2 = &s1[strlen(s1 = "plane mask = 0x00000000")];
    for (pmask = get_pmask(); pmask; pmask /= 16) {
	digit = pmask & 15;
	*- -s2 = (digit < 10) ? (digit + '0') : (digit + 'A' - 10);
    }
    text_out(10, 10, s1);
}

unsigned short get_ppop()

The get_ppop function returns the pixel-processing operation code. The 5-bit 
PPOP code determines the manner in which pixels are combined (Boolean or 
arithmetic operation) during drawing operations.

The PPOP code is right-justified in the 5 LSBs of the return value and zero- 
extended.

Legal PPOP codes are in the range 0 to 21. The source and destination pixel 
values are combined according to the selected Boolean or arithmetic operation, 
and the result is written back to the destination pixel. As shown in , Boolean 
operations are in the range 0 to 15, and arithmetic operations are in the range 
16 to 21.

Table 6-1.	Pixel-Processing Operations

PPOP Code	Description

0	replace destination with source
1	source AND destination
2	source AND NOT destination
3	set destination to all 0s
4	source OR NOT destination
5	source EQU destination
6	NOT destination
7	source NOR destination
8	source OR destination
9	destination (no change)
10	source XOR destination
11	NOT source AND destination
12	set destination to all 1s
13	NOT source or destination
14	source NAND destination
15	NOT source
16	source plus destination (with overflow)
17	source plus destination (with saturation)
18	destination minus source (with overflow)
19	destination minus source (with saturation)
20	MAX(source, destination)
21	MIN(source, destination)

The PPOP code is set to its default value of 0 (replace operation) 
during initialization of the drawing environment by the 
set_config function. The PPOP 
code can be altered with a call to the set_ppop function.

The pixel-processing operation code corresponds to the 
5-bit PPOP field in the TMS340 graphics processor's 
CONTROL register. The effects of the 22 different 
codes are described in more detail in the user's guides 
for the TMS34010 and TMS34020.

Use the get_ppop function to verify that the 
pixel-processing operation code is initialized to 0 
(replace destination with source) by a call to the 
set_config function. Use the text_out function to print 
the default PPOP code to the screen.

main()
{
    unsigned long ppop;
    char *s, c[80];

    set_config(0, !0);
    clear_screen(-1);
    ppop = get_ppop();
    strcpy(c, "PPOP code = ");
    ltoa(ppop, &c[12]);
    text_out(10, 10, c);
}

void get_text_xy(x, y)
short *x, *y;	/* text x-y coordinates */

The get_text_xy function retrieves the x-y coordinates at the 
current text drawing position. This is the position at which
the next character (or string of characters) will be drawn if a 
subsequent call is made to the text_outp function. Both
the text_outp and text_out  functions automatically update 
the text position to be the right edge of the last string 
output to the screen.

Arguments x and y are pointers to variables of type short. 
The x and y coordinate values copied by the function into
these variables correspond to the current text position 
on the screen, specified relative to the current drawing 
origin. The x coordinate corresponds to the left edge 
of the next string output by the text_outp function. 
The y coordinate corresponds either to the top of 
the string, or to the base line, depending on the 
state of the text alignment attribute (see the description
of the set_textattr function).

Use the get_text_xy  function to print four short lines of text in a stairstep 
pattern on the screen. Each time the text_outp function outputs the string 
"step" to the screen, the get_text_xy function is called next to obtain the 
current text position. The y coordinate of this position is incremented by a 
call to the set_text_xy function, and the next call to the text_outp 
function prints the string at the new position.

#include  <gsptypes.h>

main()
{
    short x, y, i;
    FONTINFO fntinf;

    set_config(0, 1);
    clear_screen(-1);
    get_fontinfo(-1, &fntinf);
    x = y = 0;
    for (i = 4; i; i--) {
	set_text_xy(x, y);
	text_outp("step");
	get_text_xy(&x, &y);
	y += fntinf.charhigh;
    }
}

short get_transp()

The get_transp function returns a value indicating 
whether transparency is enabled. A nonzero value is returned 
if transparency is enabled; 0 is returned 
if transparency is disabled.

Transparency is an attribute that affects drawing operations. 
If  transparency is enabled and the result of a pixel-processing 
operation is 0, the destination pixel is not altered. If transparency
is disabled, the destination pixel is replaced by the result 
of the pixel-processing operation, regardless of the 
value of that result. To avoid modifying destination 
pixels in the rectangular region surrounding each 
character shape, transparency can be enabled before the 
text_out or text_outp function is called.

The transparency attribute value returned by the function 
corresponds to the T bit in the TMS340 graphics processor's
CONTROL register. The effect of transparency in conjunction 
with the pixel-processing operation and the plane 
mask is described in the user's guides for the 
TMS34010 and TMS34020.

Use the get_transp function to verify that transparency is 
disabled by a call to the set_config function. Use the 
text_out function to print the value 
returned by the get_transp function to the screen.

main()
{
    unsigned long transp;
    char *s, c[80];

    set_config(0, !0);
    clear_screen(-1);
    transp = get_transp();
    strcpy(c, "transparency = ");
    ltoa(transp, &c[15]);
    text_out(10, 10, c);
}

typedef unsigned long PTR;	/* 32-bit GSP memory address */

PTR get_vector(trapnum)
short trapnum;	/* trap number */

The get_vector function returns one of the TMS340 graphics
processor's trap vectors. This function provides a portable
means of obtaining the entry point to a trap service routine, 
regardless of whether the actual trap vector is 
located in RAM or ROM.

Argument trapnum specifies a trap number in the
range -32768 to 32767 for a 
TMS34020, and 0 to 31 for a TMS34010.

The value returned by the function is the 32-bit 
address contained in the 
designated trap vector.

Use the get_vector function to retrieve whatever 
address happens to be in trap vector 0. Use the
text_out function to print the value returned by the 
get_vector function to the screen as an 8-digit 
hexadecimal number.

main()
{
    unsigned long vector;
    short digit;
    char *s1, *s2;

    set_config(0, !0);
    clear_screen(-1);
    s2 = &s1[strlen(s1 = "trap 0 vector = 0x00000000")];
    for (vector = get_vector(0); vector; vector /= 16) {
	digit = vector & 15;
	*- -s2 = (digit < 10) ? (digit + '0') : (digit + 'A' - 10);
    }
    text_out(10, 10, s1);
}

short get_windowing()

The get_windowing function returns a 2-bit code designating
the current window-checking mode. This function is provided
for the sake of backward compatibility with early versions of TIGA.

The four windowing modes are:

002	Window clipping disabled

012	Interrupt request on write to pixel inside window

102	Interrupt request on write to pixel outside window

112	Clip to window

The library's drawing functions assume that the TMS340 graphics
processor is configured in windowing mode 3. Changing the 
windowing mode from this default may result in undefined behavior.

The 2-bit code for the window-clipping mode corresponds 
to the W field in the TMS340 graphics processor's CONTROL 
register. The effects of the W field on window-clipping operations 
are described in the user's guides for the TMS34010 
and TMS34020.

Immediately following initialization of the drawing environment 
by the set_config function, the system is configured in windowing 
mode 3, which is the default.

typedef unsigned long PTR;	/* 32-bit GSP memory address */

short get_wksp(addr, pitch)
PTR *addr;	/* pointer to workspace address */
PTR *pitch;	/* pointer to workspace pitch   */

The get_wksp function retrieves the parameters that define the 
current off-screen workspace. None of the current TIGA core or
extended primitives use this workspace; it is provided to support
future graphics extensions that require storage for edge flags or 
region-of-interest masks. Not all display configurations may 
have sufficient memory to support an off-screen workspace.

Argument addr is the base address of the off-screen workspace. 
Argument pitch is the difference in memory addresses of two 
adjacent rows in the off-screen workspace.

A nonzero value is returned by the function if a valid 
off-screen workspace is currently allocated. A value of 0 
is returned if no off-screen workspace is 
allocated; in this case, the workspace address
and pitch are not retrieved by 
the function.

The off-screen workspace is a 1-bit-per-pixel bit map 
of the same width and height as the screen. If the display
hardware provides sufficient off-screen memory, the workspace 
can be allocated statically at link time. By convention, 
the workspace pitch retrieved by the get_wksp function 
is nonzero when a workspace is allocated; the pitch can be checked
following initialization to determine whether a workspace is 
statically allocated. The workspace can be allocated dynamically 
by calling the set_wksp function with the address of a 
valid workspace in memory and a nonzero pitch; it 
can be deallocated by calling set_wksp with a pitch of 0.

void gsp2gsp(src, dst, length)
char *src, *dst;	/* source and destination arrays */
unsigned long length;	/* number of bytes to copy */

The gsp2gsp function copies the specified number of bytes 
from one region of the TMS340 graphics processor's memory 
to another.

Argument src is a pointer to the source array, and argument dst is 
a pointer to the destination array. Argument length is the number
of contiguous 8-bit bytes to be transferred from the source
to the destination.

If the source and destination arrays overlap, the function is 
intelligent enough to adjust the order in which the bytes 
are transferred so that no source byte is overwritten before
it has been copied to the destination.

Unlike the standard character string function strncpy, the
gsp2gsp function does not restrict the alignment of the 
source and destination addresses to even byte boundaries in
memory. Arguments src and dst may point to any bit 
boundaries in memory.

Use the gsp2gsp function to copy three characters from a 
source string to a destination string. The source and 
destination strings overlap. Use the text_out function 
to print the resulting string, "ABCBC", to the screen.

main()
{
    static char c[80] = "AAABC";

    set_config(0, !0);
    clear_screen(-1);
    gsp2gsp(&c[2], c, 3);
    text_out(10, 10, c);
}

void init_palet()

The init_palet function initializes the first 16 entries of the
palette to the EGA default colors:

Index	Color

0	black
1	blue
2	green
3	cyan
4	red
5	magenta
6	brown
7	light gray
8	dark gray
9	light blue
10	light green
11	light cyan
12	light red
13	light magenta
14	yellow
15	white

If the palette contains more than 16 entries, the function
replicates the 16 colors through the remainder of the palette.  
At 2 bits/pixel, palette indices 0-3 are assigned the default 
colors black, green, red, and white. At 1 bit/pixel, palette 
indices 0 and 1 are assigned the default colors black and 
white. If the palette is fixed, the function has no effect.

The palette is also initialized to the default colors above 
during initialization of the drawing environment by
the set_config function.

Use the init_palet function to restore the default colors.

main()
{
    short i;

    set_config(0, !0);
    clear_screen(-1);
    for (i = 0; i < 16; i++)   	/* overwrite default colors */
	set_palet_entry(i, i, i, i, i);
    init_palet();		/* restore default colors */
}

void init_text()

The init_text function removes all installed fonts
from the font table and selects the system font (font 0) 
for use in subsequent text operations. It also 
resets all text drawing attributes to their default states. 

The set_config function also initializes the font table 
and text attributes as part of its initialization 
of the drawing environment.

Use the init_text function to discard all installed 
fonts from the font table and select the default font. 
The install_font and select_font functions from 
the Extended Primitives Library are used to install 
and select a proportionally 
spaced font. The TI Roman 
font size 16 must be linked with the program.

#include <gsptypes.h>	  /* defines FONT and FONTINFO structures */

extern FONT ti_rom16;	  /* font name */

main()
{
    FONTINFO fontinfo;
    short x, y, index;

    set_config(0, !0);
    clear_screen(-1);
    x = y = 10;
    index = install_font(&ti_rom16);
    select_font(index);
    get_fontinfo(-1, &fontinfo);
    text_out(x, y, "Hello world.");  /* print in TI Roman 16 */
    y += fontinfo.charhigh;
    init_text();
    text_out(x, y, "Hello world.");  /* print in system font */
}

short lmo(n)
unsigned long n;	/* 32-bit integer */

The lmo function calculates the bit number of the
leftmost 1 in argument n. The argument is treated as a 32-bit
number whose bits are numbered from 0 to 31, 
where bit 0 is the LSB (the rightmost bit position)
and bit 31 is the MSB (the leftmost bit position).

For nonzero arguments, the return value is in the range 
0 to 31. If the argument is 0, a value of -1 is returned.

Use the lmo function to return the bit number of the 
leftmost 1 in the integer value 1234.

#include <gsptypes.h>	    /* defines FONTINFO structure */

static FONTINFO fontinfo;

main()
{
    long x, n;
    short m;
    char c[80];

    set_config(0, !0);
    clear_screen(-1);
    get_fontinfo(-1, &fontinfo);
    x = 1234;
    n = lmo(x);
    strcpy(c, "The leftmost 1 in ");
    m = strlen(c);
    ltoa(x, &c[m]);
    text_out(10, 10, c);
    strcpy(c, "is bit number ");
    m = strlen(c);
    ltoa(n, &c[m]);
    text_out(10, 10+fontinfo.charhigh, c);
}

short page_busy()

The page_busy function returns a nonzero value as long 
as a previously requested video page flip has not yet occurred. 
This function is used in conjunction with the page_flip function
to achieve flickerless, double-buffered animation.

Before the page_busy function is called, the page_flip function
is called to request the page flip, which is scheduled to occur when 
the bottom line of the screen has been scanned on the monitor. 
The page_flip function returns immediately without waiting 
for the requested page flip to be completed, and 
the page_busy function is used thereafter to monitor the 
status of the request. Between the call to the page_flip 
function and the time the page flip actually occurs, 
the page_busy function returns a nonzero value. After 
the page flip has occurred, the page_busy returns a 
value of 0 (until the next time page_flip is called).

Double buffering is a technique used to achieve 
flickerless animation in graphics modes supporting
more than one video page. The TMS340 graphics 
processor alternately draws to one page (or frame 
buffer) while the other page is displayed on the
screen of the monitor. When the  processor has finished 
drawing, the new page is ready to be displayed on the
screen in place of the old. The actual flipping 
(or switching) of display pages is delayed until the 
vertical blanking interval, however, to avoid 
causing the image on the screen to flicker.

The rationale for providing separate page_flip 
and page_busy functions is to make the time 
between between a page-flip request and the 
actual completion of the page flip available to the 
application program for performing background 
calculations. For example, the main loop of a 3D 
animation program can be structured as follows:

    for (disp = 1, draw = 0; ; disp ^= 1, draw ^= 1) {
	page_flip(disp, draw);
	< Perform 3D background calculations. >
	while (page_busy())
	    ;
	< Draw updated 3D scene. >
    }

If the page_flip function is used alone without the page_busy
function, the programmer risks drawing to a page that is 
still being displayed on the screen.

Use the page_busy function to smoothly animate an
object rotating in a circle. The best effect is achieved
in a graphics mode that provides double buffering 
(more than one video page). If the mode supports 
only a single page, the program will still run correctly,
but the display may flicker.

#define  RADIUS  60    /* radius of circle of rotation */
#define  N        4    /* angular increment = 1>>N radians */

main()
{
    short disp, draw;
    long x, y;

    set_config(0, !0);
    x = RADIUS << 16;
    y = 0;
    for (disp = 0, draw = 1; ; disp ^= 1, draw ^= 1) {
	page_flip(disp, draw);
	x -= y >> N;
	y += x >> N;
	while (page_busy())
	    ;
	clear_page(-1);
	text_out((x>>16)+RADIUS, (y>>16)+RADIUS, "*");
    }
}

void page_flip(disp, draw)
short disp, draw;	/* display and drawing pages */

The page_flip function is used to switch between 
alternate video pages. This function is used in conjunction 
with the page_busy function to achieve 
flickerless, double-buffered animation.

Argument disp is a nonnegative value indicating the number 
of the video page to be displayed-that is, output to the monitor 
screen. Argument draw is a nonnegative value indicating
the number of the video page to be drawn to; this 
page is the target of all graphics output directed to 
the screen. All graphics modes support at least one 
video page, page number 0. In graphics modes 
supporting more than one page, the pages are 
numbered 0, 1, and so on.

Valid values for arguments disp and draw are 
restricted to video page numbers supported by the 
current graphics mode. If either argument is invalid, the 
function behaves as if both arguments are 0; that is, 
page 0 is selected as both the display page and drawing
page. This behavior permits programs written 
for double-buffered modes to be run in single-buffered 
modes. Although the single-buffered display may flicker, 
the program will execute at nearly the 
same frame rate as in the double-buffered mode.

The number of pages in a particular graphics mode is
specified in the num_pages field of the CONFIG structure 
returned by the get_config function. If the num_pages 
field contains some value N, the N pages are numbered 0 through N-1.

The page_flip function requests that a page flip be performed 
but returns immediately without waiting for the requested page flip 
to be completed. Upon return from the function, all subsequent 
screen drawing operations are directed toward the page specified 
by argument draw. The monitor display, however, is 
not updated to the page specified by argument disp 
until the start of the next vertical blanking interval 
(which occurs when the monitor finishes scanning the 
last line on the screen). Between the call to the page_flip 
function and the time the page flip actually occurs, the page_busy 
function returns a nonzero value. This is true regardless of whether 
the disp and draw arguments are the 
same or whether the new display page is the same as the 
old display page. After the page flip has occurred, 
the page_busy returns a value of 0 (until the next 
time page_flip is called).

Double buffering is a technique used to achieve 
flickerless animation in graphics modes supporting more 
than one video page. The TMS340 graphics 
processor alternately draws to one page (or frame buffer) 
while the other page is displayed on the screen of the monitor. 
When the  processor has finished drawing, the new page
is ready to be displayed on the screen in place of the 
old. The actual flipping (or switching) of display pages is 
delayed until the vertical blanking interval, however, 
to avoid causing the image on the screen 
to flicker.

Use the page_flip function to smoothly animate two 
moving rectangles. Use the fill_rect  function from the 
Extended Primitives Library to draw the rectangles. 
The selected graphics mode is assumed to be double-buffered-that 
is, to support more than one video page. If the mode supports
only a single page, the program will still run correctly, 
but the display may flicker.

#define  RADIUS 60	/* radius of circle of rotation */
#define  XOR	10	/* pixel processing operation code */
#define  N	5	/* angular increment = 1>>N radians */

main()
{
    short disp, draw;
    long x, y;

    set_config(1, !0);
    set_ppop(XOR);
    x = RADIUS << 16;
    y = 0;
    for (disp = 0, draw = 1; ; disp ^= 1, draw ^= 1) {
	page_flip(disp, draw);
	x -= y >> N;
	y += x >> N;
	while (page_busy())
	    ;
	clear_screen(-1);
	fill_rect(2*RADIUS, RADIUS/4, 10, RADIUS+(y>>16));
	fill_rect(RADIUS/4, 2*RADIUS, RADIUS+(x>>16), 10);
    }
}

unsigned long peek_breg(breg)
short breg;	/* B-file register number */

The peek_breg function returns the contents of a B-file register. 
Argument breg is a number in the range 0 to 15 that designates
a register in the TMS340 graphics processor's B file. Argument 
values 0 through 14 correspond to registers B0 through B14. 
An argument value of 15 designates the SP (system stack pointer). 
The function ignores all but the 4 LSBs of argument breg. The 
return value is 32 bits.

Use the peek_breg function to read the contents of register B9, 
also referred to as the COLOR1 register. Register B9 contains 
the foreground color in pixel-replicated form. For example, 
at 4 bits per pixel, a foreground pixel value of 7 is replicated 8
times to form the 32-bit value 0x77777777.

main()
{
    unsigned long n;
    short digit;
    char *s1, *s2;

    set_config(0, !0);
    clear_screen(-1);
    s2 = &s1[strlen(s1 = "COLOR1 = 0x00000000")];
    for (n = peek_breg(9); n; n /= 16) {
	digit = n & 15;
	*- -s2 = (digit < 10) ? (digit + '0') : (digit + 'A' - 10);
    }
    text_out(10, 10, s1);
}

void poke_breg(breg, val)
short breg;		/* B-file register number   */
unsigned long val;	/* 32-bit register contents */

The poke_breg function loads a 32-bit value into a 
B-file register. Argument breg is a number in the range 0 
to 15 that designates a register in the TMS340 
graphics processor's B file. Argument values 0 through
14 correspond to registers B0 through B14. An argument 
value of 15 designates the SP (system stack pointer). 
The function ignores all but the 4 LSBs of argument breg. 
Argument val  is a 32-bit value that is loaded 
into the designated register.

Use the poke_breg function to load the value 0 
into the TMS340 graphics processor's register B6, 
also referred to as the WEND register. Use the 
fill_rect  function from the Extended Primitives 
Library to draw a filled rectangle that is specified to 
be larger than the clipping window. Register B6 
contains the upper x and y limits for the clipping 
window. Following the poke_breg call, the clipping 
window contains only the single pixel at (0, 0). 
Obviously, the set_clip_rect function provides a 
safer and more portable means to adjust the clipping 
window than the one used in this example.

main()
{
    set_config(0, !0);
    clear_screen(-1);
    poke_breg(6, 0);
    fill_rect(100, 100, 0, 0);
}

short rmo(n)
unsigned long n;	/* 32-bit integer */

The rmo function calculates the bit number of the rightmost 
1 in argument n. The argument is treated as a 32-bit number 
whose bits are numbered from 0 to 31, where bit 0 is the LSB 
(the rightmost bit position) and bit 31 is the MSB 
(the leftmost bit position).

For nonzero arguments, the return value is in the range 0 to 31.
If the argument is 0, a value of -1 is returned.

Use the rmo function to calculate the bit number of the rightmost 
1 for each integer in the range 1 to 127. Represent the result 
graphically as a series of 127 adjacent vertical lines. Use the
fill_rect function from the Extended Primitives Library to 
draw the vertical lines.

main()
{
    unsigned long i;
    short n;

    set_config(0, !0);
    clear_screen(-1);
    for (i = 1; i < 128; i++) {
	n = rmo(i);
	fill_rect(1, 8*n, 10+i, 10);
    }
}

void set_bcolor(color)
unsigned long color;	/* background pixel value */

The set_bcolor function sets the background color for 
subsequent drawing operations.

Argument color specifies the pixel value to be used to 
draw background pixels. Given a pixel size of N bits, 
the pixel value is contained in the N LSBs of the 
argument; the higher-order bits are ignored.

The function creates a 32-bit replicated pixel value and 
loads the result  into the  TMS340  graphics  processor's 
register  B8, also referred to as the  COLOR0 register. 
For example, given a pixel size of 4 bits and a pixel value of 
6, the replicated pixel value is 0x66666666.

Use the set_bcolor function to swap the foreground
and background colors.

main()
{
    unsigned long fcolor, bcolor;

    set_config(0, !0);
    clear_screen(-1);
    get_colors(&fcolor, &bcolor);
    set_fcolor(bcolor);
    set_bcolor(fcolor);
    text_out(10, 10, "Swap COLOR0 and COLOR1.");
}

void set_clip_rect(w, h, xleft, ytop)
unsigned short w, h;	/* width, height of clip window */
short xleft, ytop;	/* coordinates at top left corner */

The set_clip_rect function specifies the position and size of
the rectangular clipping window for subsequent drawing 
operations.

Arguments w and h specify the width and height of the 
clipping window in pixels. Arguments xleft and ytop specify 
the x and y coordinates at the top-left corner of the window, 
relative to the drawing origin in effect at the 
time set_clip_rect is called.

If the specified clipping window extends beyond the screen 
boundaries, the effective window is limited by the function
to that portion of the specified window that actually
lies on the screen.

A call to the set_draw_origin function (in the Extended 
Primitives Library) has no effect on the position of the 
clipping window until the set_clip_rect function is 
called. During initialization of the drawing environment by 
the set_config function, the clipping window is set to its 
default limits, which are the entire screen.

The function updates the contents of the TMS340 graphics 
processor's registers B5 and B6, which are also referred
to as the WSTART (window start) and WEND 
(window end) registers. These registers are described in 
the user's guides for the TMS34010 and TMS34020.

Use the set_clip_rect  function to specify a clipping window
of width 192 pixels and height 128 pixels. Use the draw_line 
function to draw a series of concentric rays that emanate from a 
point within the window, but which extend 
beyond the window. The rays are automatically clipped to 
the limits of the window. Note that the call to set_clip_rect
follows the call to the set_draw_origin function, and that the
x-y coordinates (-80, -80) passed as 
arguments to set_clip_rect are specified relative 
to the drawing origin at (88, 88).

main()
{
    int i;
    long x, y;

    set_config(0, !0);
    clear_screen(-1);
    set_draw_origin(88, 88);
    set_clip_rect(192, 128, -80, -80);
    x = 160 << 16;
    y = 0;
    for (i = 0; i <= 100; i+ +) {
	draw_line(0, 0, x>>16, y>>16);
	x -= y >> 4;
	y += x >> 4;
    }
}

void set_colors(fcolor, bcolor)
unsigned long fcolor;	/* foreground pixel value */
unsigned long bcolor;	/* background pixel value */

The set_colors function specifies the foreground and 
background colors to be used in subsequent drawing operations.

Arguments fcolor and bcolor contain the pixel values used to 
draw the foreground and background colors, respectively. 
Given a pixel size of N bits, the pixel value is contained in the
N LSBs of each argument; the higher-order bits are ignored.

The function creates 32-bit replicated pixel values and loads 
the results into the TMS340 graphics processor's registers 
B8 and B9, also referred to as the COLOR0 and COLOR1 
registers. For example, given a pixel size of 4 bits and a 
pixel value of 3, the replicated pixel value is 0x33333333.

Use the set_colors function to swap the default foreground 
and background colors. Use the text_out function to print a 
string of text with the colors swapped.

main()
{
    long white, black;

    set_config(0, !0);
    clear_screen(-1);
    get_colors(&white, &black);
    set_colors(black, white);
    text_out(8, 8, "Black text on white background.");
}

short set_config(graphics_mode, init_draw)
short graphics_mode;	/* graphics mode */
short init_draw;	/* initialize drawing environment */

The set_config function configures the display system in 
the specified graphics mode. Both the display hardware and 
graphics software environment are initialized. With few 
exceptions, set_config should be called before any of the 
other functions in the graphics library are called.

Argument graphics_mode specifies the graphics mode. All display 
systems provide at least one graphics mode, mode 0. In display 
systems supporting multiple modes, the modes are numbered 0, 1, 
and so on.

Argument init_draw specifies whether the function initializes the 
drawing environment to its default state. If init_draw is nonzero, 
the environment is initialized; otherwise, the drawing 
environment remains unaltered.

The value returned by the function is nonzero if argument 
graphics_mode corresponds to a valid graphics mode-that is, 
a mode supported by the display system. If the specified mode 
number is invalid, the function performs no 
operation and returns a value of 0.

The number of modes available for a particular hardware 
configuration is specified in the num_modes field of the 
CONFIG structure returned by the get_config function. 
The modes are numbered 0 through num_modes - 1.

Following a call to set_config, the display system remains 
in the specified graphics mode until a subsequent call to set_config 
is made. Associated with each mode is a particular display 
resolution, pixel size, and so on.

The set_config function configures the following system 
parameters:

	horizontal and vertical video timing

	video-RAM screen-refresh cycles

	screen pixel size in bits

	screen dimensions (width and height in pixels)

	location in memory of one or more video pages (or frame buffers)

	default clipping window (entire screen)

	default color palette (See description of init_palet function.)

	default display and drawing pages (page 0 for both)

	default off-screen workspace (which may be null)

If a nonzero value is specified for argument init_draw, the parameters 
of the drawing environment are initialized as follows:

	Pixel transparency is disabled.

	The pixel-processing operation code is set to its default value of 0 
	(the code for the replace operation).

	The plane mask is set to its default value of 0, which 
	enables all bit planes.

	The foreground color is set to light gray and the 
	background color to black.

	The screen is designated as both the source bit map 
	and destination bit map.

	The drawing origin is set to screen coordinates (0, 0), 
	which correspond to the pixel at the top left corner 
	of the screen.

	The pen width and height are both set to 1.

	The current area-fill pattern is set to its default state, 
	which is to fill with solid foreground color.

	The current line-style pattern is set to its default value, 
	which is all 1s.

	All installed fonts are removed, and font 0, the
	permanently installed system font, is selected.

	The text  x-y position coordinates are set to (0,0).

	The text attributes are set to their initial states:

	- alignment = 0 (top left)

	- additional intercharacter spacing = 0

	- intercharacter gaps = 0 (leave gaps)

Use the set_config function to sequence the display through all 
available graphics modes. Use the draw_rect  function to draw 
a box around the visible screen area, and use the text_out 
function to print the mode number and screen 
width and height to the screen. Use the wait_scan 
function to insert a delay of 120 frames 
between mode switches.

#include <gsptypes.h>	    /* MODEINFO, CONFIG and FONTINFO */
#define  NFRAMES    120     /* delay in frames between modes */

main()
{
    CONFIG cfg;
    char c[80];
    short mode, i, w, h;

    for (;;)
	for (mode = 0; set_config(mode, !0); mode++) {
	    clear_screen(-1);
	    get_config(&cfg);
	    w = cfg.mode.disp_hres;
	    h = cfg.mode.disp_vres;
	    draw_rect(w-1, h-1, 0, 0);
	    i = strlen(strcpy(c, "graphics mode "));
	    i += ltoa(mode, &c[i]);
	    strcpy(&c[i], "...");
	    i = strlen(c);
	    i += ltoa(w, &c[i]);
	    strcpy(&c[i], "-by-");
	    i = strlen(c);
	    ltoa(h, &c[i]);
	    text_out(10, 10, c);
	    for (i = NFRAMES; i; i- -) /* delay loop */
		wait_scan(h);
	}
}

void set_fcolor(color)
unsigned long color;	/* foreground pixel value */

The set_fcolor function sets the foreground color for
subsequent drawing operations.

Argument color specifies the pixel value to be used to 
draw foreground pixels. Given a pixel size of N bits, the
pixel value is contained in the N LSBs of the 
argument; the higher-order bits are ignored.

The function creates a 32-bit replicated pixel value 
and loads the result into the TMS340 graphics 
processor's register B9, also referred to as the COLOR1 
register. For example, given a pixel size of 8 bits and a 
pixel value of 5, the replicated pixel value is 0x05050505.

Use the set_fcolor  function to swap the foreground and 
background colors.

main()
{
    unsigned long fcolor, bcolor;

    set_config(0, !0);
    clear_screen(-1);
    get_colors(&fcolor, &bcolor);
    set_fcolor(bcolor);
    set_bcolor(fcolor);
    text_out(10, 10, "Swap COLOR0 and COLOR1.");
}

typedef struct { unsigned char r, g, b, i; } PALET;

void set_palet(count, index, palet)
long count;	/* number of palette entries */
long index;	/* index to starting entry */
PALET *palet;	/* list of palette data */

The set_palet function loads multiple palette entries 
from a specified list of colors.

Argument count specifies the number of contiguous 
palette entries to be loaded. Argument index designates
the palette entry at which loading is to begin. 
Argument palet is an array containing the colors to 
be loaded into the palette. The palet array must 
contain at least count elements. The palette entry 
identified by index is loaded from palet [0], 
and so on.

Argument palet is an array of type PALET. Each array 
element is a structure containining r, g, b, and i fields. Each 
field specifies an 8-bit red, green, blue, or gray-scale intensity 
value in the range 0 to 255, where 255 is the 
brightest intensity and 0 is the darkest. In the case of
a graphics mode for a color display, the r, g, and b fields from 
each array element are loaded into the red, green, and blue 
component intensities for the corresponding palette 
entry; the i field from the element is ignored, and
the gray-scale intensity component for the palette entry
is set to 0. In the case of a gray-scale mode, 
the i field from each array element is loaded into the 
gray-scale intensity value for the corresponding palette
entry; the r, g, and b fields from the 
element are ignored, and the red, green, and blue 
intensities for the palette entry are set to 0.

The range of palette entries to be loaded is checked 
by the function to ensure that it does not overflow 
the palette. If the starting index plus the number of 
entries (count ) is greater than the palette size, 
the function decreases the count value by the 
appropriate amount.

The entire palette may be loaded at once by specifying 
a count equal to the number of palette entries, and an
index of 0. The number of palette entries in 
the current graphics mode is specified in the 
palet_size field of the CONFIG 
structure returned by the get_config function.

The 8-bit r, g, b, and i values contained in the palet 
array are modified by the function to represent the 
color components or gray-scale intensity actually 
output by the physical display device. For example, 
assume that the r, g, b, and i values of a particular array 
element are specified as  follows: r = 0xFF, 
g = 0xFF, b = 0xFF, and i = 0. If the display hardware
supports only 4 bits of red, green, and blue intensity per 
gun, the values actually loaded into the palette by the 
set_palet function are:  r = 0xF0, g = 0xF0, b = 0xF0, 
and i = 0.

In systems that store the palette data in display memory 
(such as those using the TMS34070 color palette), this
function updates every palette area in the frame buffer. 
If the system contains multiple display pages, the function 
updates the palette area for every page.

Use the set_palet  function to load a gray-scale palette into 
the first 16 color palette entries. Use the fill_rect function
from the Extended Primitives Library to fill a series of 
rectangles in intensities increasing from left to 
right. Note that this example requires a color palette 
with a capacity of at least 16 entries.

#include  <gsptypes.h>	   /* defines PALET struct */

main()
{
    int n;
    PALET p[16];

    set_config(0, !0);
    clear_screen(-1);
    for (n = 0; n < 15; n++)
	p[n].r = p[n].g = p[n].b = p[n].i = 16*n;
    set_palet(16, 0, p);
    for (n = 0; n < 15; n++) {
	set_fcolor(n);
	fill_rect(12, 80, 8+12*n, 8);
    }
}

short set_palet_entry(index, r, g, b, i)
long index;		/* index to palette entry */
unsigned char r, g, b;	/* red, green and blue components */
unsigned char i;	/* gray-scale intensity */

The set_palet_entry function updates a single entry in the 
color palette.

Argument index identifies the palette entry to be updated. 
Arguments r, g, b, and i specify 8-bit red, green, blue, and
gray-scale intensity values in the range 0 to 255, where 255 is 
the brightest intensity and 0 is the darkest. If 
the current graphics mode supports a color display, 
arguments r, g, and b are the red, green, and blue component 
intensities. In the case of a gray-scale 
display, argument i is the gray-scale intensity.

If the palette contains N entries, the valid range 
of argument index is 0 through N-1. The number of palette
entries in the current graphics mode is 
specified in the palet_size field of the 
CONFIG structure returned by the 
get_config function.

If argument index specifies an invalid value, 
the function aborts (returns immediately) and
returns a value of 0; otherwise, a nonzero value is returned.

In systems that store the palette data in display memory 
(such as those using the TMS34070 color palette), 
this function updates every palette area in the 
frame buffer. If the system contains multiple 
display pages, the function 
updates the palette area for every page.

Use the set_palet_entry  function to load a gray-scale palette 
into the first 16 color palette entries. Use the fill_rect 
function from the Extended Primitives Library to fill a
series of rectangles in intensities increasing 
from left to right. Note that this example requires a
color palette with a capacity of at least 16 entries.

main()
{
    int n;

    set_config(0, !0);
    clear_screen(-1);
    for (n = 0; n < 15; n++)
	set_palet_entry(n, 16*n, 16*n, 16*n, 16*n);
    for (n = 0; n < 15; n++) {
	set_fcolor(n);
	fill_rect(12, 80, 8+12*n, 8);
    }
}

void set_pmask(pmask)
unsigned long pmask;	/* plane mask */

The get_pmask  function sets the plane mask to the specified
value. The size of the plane mask in bits is the 
same as the pixel size.

Argument pmask contains the plane mask. Given a pixel size 
of N bits, the plane mask is right-justified in the N LSBs 
of the argument; the higher-order bits 
are ignored by the function.

The plane mask designates which bits within a pixel are 
protected against writes and affects all operations on 
pixels. During writes, the 1s in the plane 
mask designate bits in the destination pixel that 
are protected against modification, while the 0s in the 
plane mask designate bits that can be 
altered. During reads, the 1s in the plane
mask designate bits in the source 
pixel that are read as 0s, while the 0s in 
the plane mask designate bits that 
can be read from the source pixel as is.

The plane mask is set to its default value of 0 during
initialization of the drawing environment by the set_config 
function. The plane mask can be altered 
with a call to the set_pmask function.

The plane mask corresponds to the contents of the
TMS340 graphics processor's PMASK register. The
effect of the plane mask in conjunction with the 
pixel-processing operation and the transparency
mode is described in the user's 
guides for the TMS34010 and TMS34020.

Use the set_pmask function to demonstrate the effects 
of enabling and disabling particular bit planes. For each 
bit plane, print a line of text with all but 
the one plane enabled; print another line of 
text with only the one plane enabled. This example 
assumes that the display has at least 4 bit planes - that 
is, a pixel size of at least 4 bits.

#include  <gsptypes.h>		/* defines CONFIG and FONTINFO */
#define   MINPSIZE	4	/* minimum pixel size */

main()
{
    CONFIG cfg;
    FONTINFO fntinf;
    unsigned long pmask;
    short x, y, n;
    char c[80];

    set_config(0, !0);
    clear_screen(-1);
    get_config(&cfg);
    get_fontinfo(-1, &fntinf);
    x = y = 10;
    for (pmask = 1; pmask != 1<<MINPSIZE; pmask <<= 1) {

	/* Enable all planes except one. */
	set_pmask(pmask);
	n = strlen(strcpy(c, "all planes enabled except "));
	ltoa(lmo(pmask), &c[n]);
	text_out(x, y, c);
	y += fntinf.charhigh;

	/* Disable all planes except one. */
	set_pmask(~pmask);
	n = strlen(strcpy(c, "all planes disabled except "));
	ltoa(lmo(pmask), &c[n]);
	text_out(x, y, c);
	y += fntinf.charhigh;
    }
}

void set_ppop(ppop)
short ppop;	/* pixel processing operation code */

The set_ppop function specifies the pixel-processing operation
to be used for subsequent drawing operations. The specified 
Boolean or arithmetic operation determines the manner in which 
source and destination pixel values are combined 
during drawing operations.

Argument ppop is a pixel-processing operation code in the range
0 to 21. The PPOP code is right-justified in the 5 LSBs of the 
argument; the higher-order bits are ignored by the function.

Legal PPOP codes are in the range 0 to 21. The source and 
destination pixel values are combined according to the 
selected Boolean or arithmetic operation, and the result is written
back to the destination pixel. As shown in Table 6-2, Boolean 
operations are in the range 0 to 15, and arithmetic operations
are in the range 16 to 21.

Table 6-2.	Pixel-Processing Operations

PPOP Code		Description

0		replace destination with source
1		source AND destination
2		source AND NOT destination
3		set destination to all 0s
4		source OR NOT destination
5		source EQU destination
6		NOT destination
7		source NOR destination
8		source OR destination
9		destination (no change)
10		source XOR destination
11		NOT source AND destination
12		set destination to all 1s
13		NOT source or destination
14		source NAND destination
15		NOT source
16		source plus destination (with overflow)
17		source plus destination (with saturation)
18		destination minus source (with overflow)
19		destination minus source (with saturation)
20		MAX(source, destination)
21		MIN(source, destination)

When initialized by the set_config function, the PPOP code is set to its 
default value of 0 (replace operation). The PPOP code can be altered 
with a call to the set_ppop function.

The pixel-processing operation code corresponds to the 5-bit 
PPOP field in the TMS340 graphics processor's CONTROL 
register. The effects of the 22 different codes are described 
in more detail in the user's guides for the TMS34010 and 
TMS34020.

Use the set_ppop function to set the current pixel-processing 
operation code to 10 (exclusive-OR ). Use the fill_rect 
function from the Extended Primitives Library to fill 
two rectangles that partially overlap. The overlapping region 
shows the effect of exclusive-ORing identical source and 
destination pixel values.

#define  XOR   10          /* pixel processing operation code */

main()
{
	set_config(0, !0);
	clear_screen(-1);

	set_ppop(XOR);
	fill_rect(100, 20, 10, 50);
	fill_rect(20, 100, 50, 10);
}

void set_text_xy(x, y)
short x, y;	/* text x-y coordinates */

The set_text_xy function sets the text-drawing position 
to the specified x-y coordinates. This is the position 
at which the next character (or string of characters) will 
be drawn if a subsequent call is made to the text_outp 
function. Both the text_outp and text_out functions 
automatically update the text position to be the right
edge of the last string output to the screen.

Arguments x and y are the coordinates of the new 
text position on the screen, specified relative to the 
current drawing origin. Argument x is the x 
coordinate at the left edge of the next string 
output by the text_outp function. Argument y is 
the y coordinate at either the top of the string, or 
the base line, depending on the state of the text 
alignment attribute (see the 
description of the set_textattr function).

Use the set_text_xy function to set the text-drawing 
position to x-y coordinates (10, 20). Use the text_outp
function to print a text string to the 
screen starting at these coordinates.

main()
{
    set_config(0, 1);
    clear_screen(-1);
    set_text_xy(10, 20);
    text_outp("hello, world");
}

void set_transp(mode)
short mode;	/* transparency mode */

The set_transp function, if implemented, changes the 
transparency mode. When transparency is enabled, this 
mode determines the manner in which a pixel is determined
to be transparent. During a graphics output operation, a 
nontransparent pixel replaces the original destination 
pixel but a transparent pixel does not. 

The set_transp function is implemented only on 
TMS34020 systems. Currently, the 
modes supported on TMS34020 systems are

mode = 0 	Transparent if result equal to zero

mode = 1 	Transparent if source equal to COLOR0

mode = 5 	Transparent if destination equal to COLOR0

Argument mode must be set to one of these values. Specifying 
an invalid mode number may result in undefined behavior.

On TMS34010 systems, the set_transp function is not 
implemented and only transparency mode 0 is supported.

The enabling and disabling of transparency, regardless 
of the mode selected, is performed by two other functions, 
transp_on and transp_off. Refer to the 
descriptions of these functions for more information.

Immediately after initialization of the drawing 
environment by the set_config function, the system 
is configured in transparency mode 0, which is the 
default.

typedef unsigned long PTR; 	/* 32-bit GSP memory address */

PTR set_vector(trapnum, gptr)
unsigned short trapnum; 	/* trap number */
PTR gptr;			/* pointer to GSP memory */

The set_vector function loads one of the TMS340 graphics 
processor's trap vectors with a pointer to a location in the 
processor's memory. This function provides a portable means
of loading the entry point to a trap service routine, regardless of 
whether the actual trap vector is located in RAM or ROM.

Argument trapnum specifies a trap number in the range -32768
to 32767 for a TMS34020, and 0 to 31 for a TMS34010. 
Argument gptr is a pointer containing the 
32-bit memory address to be loaded into the trap vector.

The value returned by the function is the original 32-bit TMS340
graphics processor address contained in the designated 
trap vector at the time of the call.

Use the set_vector  function to load the trap-3 vector 
with the address of a trap service routine. The service routine 
simply increments a global counter. The progress of the
count is displayed graphically on the screen as a moving 
asterisk. Note that the C compiler recognizes "c_int03" as 
the name of an interrupt routine and terminates the 
routine with a RETI (return from 
interrupt) rather than a RETS (return from subroutine) 
instruction.

#include  <gsptypes.h>		/* defines CONFIG and FONTINFO */
static long count;

c_int03()
{
    count++;
}

main()
{
    int n;
    char c[40];

    set_config(0, !0);
    clear_screen(-1);
    for (n = 0; n < 32; n++)
	c[n] = ' ';
    c[32] = '\0';

    /* Install trap service routine. */
    count = 0;
    set_vector(3, c_int03);

    /* Trap once per loop. */
    for (n = 0; ; ) {
	asm("    TRAP   3    ");
	c[n] = ' ';
	c[n = count/32 & 31] = '*';
	text_out(10, 10, c);
    }
}

void set_windowing(mode)
short mode;

The set_windowing function loads the specified value into
the 2-bit windowing field contained in the CONTROL 
I/O register. This function is provided for the 
sake of backward compatibility with early versions of TIGA.

The four windowing modes are

002	No windowing.

012	Interrupt request on write in window.

102	Interrupt request on write outside window.

112	Clip to window.

Take care in using this function. The library's drawing functions 
assume that the TMS340 graphics processor is configured in
windowing mode 3. Changing the windowing mode from this
default may result in undefined behavior. The code 
specified for the window-clipping mode corresponds 
to the 2-bit W field in the TMS340 graphics processor's 
CONTROL register. The effects of the W field on 
window-clipping operations are described in the user's 
guides for the TMS34010 and TMS34020.

Immediately following initialization of the drawing 
environment by the set_config function, the system is 
configured in windowing mode 3, which is the default.

typedef unsigned long PTR; 	/* 32-bit GSP memory address */

void set_wksp(addr, pitch)
PTR addr;	/* starting address */
PTR pitch;	/* workspace pitch */

The set_wksp function specifies an off-screen workspace. 
None of the current TIGA core or extended primitives 
makes use of this workspace; it is provided to 
support future graphics extensions that require 
storage for edge flags or region-of-interest masks.

Argument addr is the base address of the off-screen workspace. 
Argument pitch is the difference in memory addresses of two 
adjacent rows in the off-screen workspace. 
The pitch is required to be a power of two and a multiple of 16. 
The exception to this requirement is that the pitch argument 
is specified as 0 in the event that no workspace is allocated 
(in which case the value of the addr argument is a "don't care.")

The off-screen workspace is a 1-bit-per-pixel bit map of 
the same width and height as the screen. If the display 
hardware provides sufficient off-screen 
memory, the workspace can be allocated statically 
at link time. By convention, the workspace pitch retrieved
by the get_wksp function is nonzero when a 
workspace is allocated; the pitch can be 
checked following initialization to determine whether a 
workspace is statically allocated. The workspace can be 
allocated dynamically by calling the set_wksp 
function with the address of a valid workspace in memory 
and a nonzero pitch; it can be deallocated by calling 
set_wksp with a pitch of 0.

Not all TMS340 graphics processor-based display 
configurations may contain sufficient memory to 
allocate (statically or dynamically) an off-screen 
workspace. For this reason, proprietary extensions 
to the Core Primitives Library that require use of 
the workspace may be unable to execute on some systems.

short text_out(x, y, s)
short x, y;		/* starting coordinates */
unsigned char *s;	/* character string */

The text_out function draws a character string to the screen in
the currently selected font.

Arguments x and y are the starting coordinates of the string, 
relative to the current drawing origin. Argument s is a 
string of 8-bit ASCII characters terminated by a null (0) character.

The string is rendered in the currently selected font using
the current text-drawing attributes.

Argument x is the x coordinate at the left edge of the string. 
Argument y is the y coordinate at either the top of the 
string or the base line, depending on the state of the text
alignment attribute. During initialization of the drawing 
environment by the set_config function, the alignment is 
set to its default position, at the top left corner. The attribute
can be modified by means of a call to the set_textattr function.

The return value is the x coordinate of the next character 
position to the right of the string. If the string lies entirely 
above or below the clipping 
rectangle, the unmodified starting x coordinate is returned.

Use the text_out function to write a single line of text to the 
screen in the system font.

main()
{
    set_config(0, !0);
    clear_screen(-1);
    text_out(10, 10, "Hello world.");
}

void text_outp(s)
unsigned char *s;

The text_outp function outputs text to the screen, starting 
at the current text drawing position. The specified string of 
characters is rendered in the currently selected font and with the 
current text-drawing attributes. The text 
position must have been specified by a previous call to
the set_text_xy, text_out or text_outp function.

Argument s is a string of 8-bit ASCII character codes terminated 
by a null (0) character.

After printing the text on the screen, the function automatically 
updates the text position to be the position of the next character 
to the right of the string just printed. A subsequent call to the 
text_outp function will result in the next string being printed
beginning at this position.

Unlike the text_out function, the text_outp function does not
return a value.

Use the text_outp function to mix two fonts in the same line of of text. 
The TI Roman size 20 and TI Helvetica size 22 fonts will be used. 
Use the set_textattr function to align the text to the base line.

#include <gsptypes.h>		/* FONT type definition */

extern FONT ti_rom20, ti_hel22;	/* 2 different fonts    */

static FONTINFO fontinfo;

main()
{
    int i, j;

    set_config(0, 1);
    clear_screen(-1);
    i = install_font(&ti_rom20);
    j = install_font(&ti_hel22);
    set_textattr("%1a", 0, 0);
    select_font(i);
    get_fontinfo(0, &fontinfo);
    set_text_xy(0, fontinfo.charhigh);
    text_outp(" Concatenate");
    select_font(j);
    text_outp(" one font");
    select_font(i);
    text_outp(" with another.");
}

void transp_off()

The transp_off function disables transparency for 
subsequent drawing operations.

Transparency is an attribute that affects drawing 
operations. Several transparency modes are supported. 
During initialization of the drawing environment by the 
set_config function, transparency is disabled and the 
transparency mode is set to the default, mode 0. The 
TMS34010 supports only 
transparency mode 0, but the TMS34020 supports 
additional modes. Refer to the description of the
set_transp function for details.

In transparency mode 0, if transparency is enabled and
the result of a pixel-processing operation is 0, the destination 
pixel is not altered. If transparency is disabled, the destination 
pixel is replaced by the result of the pixel-processing operation, 
regardless of the value of that result. For instance, to avoid 
modifying destination pixels in the rectangular region 
surrounding each character shape, you can enable transparency 
before you call the text_out or text_outp  function.

The effect of transparency in conjunction with the 
pixel-processing operation and the plane mask is described 
in the user's guides for the TMS34010 and 
TMS34020.

Use the transp_off  function to demonstrate the effect of 
disabling transparency. Use the draw_rect function from 
the Extended Primitives Library to construct a background pattern. 
To show that the background pattern is preserved in the rectangle 
surrounding each character, use the text_out  
function to draw a line of text to the screen with 
transparency enabled. Also, draw a line of text to the 
screen with transparency disabled to show that the 
background pattern is overwritten.

#include  <gsptypes.h>		/* defines FONTINFO structure */

main()
{
    short x, y;
    FONTINFO fntinf;

    set_config(0, !0);
    clear_screen(-1);
    get_fontinfo(-1, &fntinf);
    for (x = y = 0; x < 200; x += 15)
	draw_rect(8, 80, x, y);
    x = y = 10;
    transp_on();
    text_out(x, y, "Transparency enabled.");
    transp_off();
    text_out(x, y+fntinf.charhigh, "Transparency disabled.");
}

void transp_on()

The transp_on function enables transparency for subsequent
drawing operations.

Transparency is an attribute that affects drawing operations. Several 
transparency modes are supported. During initialization of the 
drawing environment by the set_config function, transparency is 
disabled and the transparency mode is set to the default, mode 0. 
The TMS34010 supports only transparency mode 0, but the TMS34020 
supports additional modes. Refer to the 
description of the set_transp function for details.

In transparency mode 0, if transparency is enabled and the 
result of a pixel-processing operation is 0, the destination pixel is not 
altered. If transparency is disabled, the destination pixel is replaced 
by the result of the pixel-processing operation, regardless of the value 
of that result. For instance, to avoid modifying destination pixels 
in the rectangular region surrounding each character shape, 
you can enable transparency before you call 
the text_out or text_outp  function.

The effect of transparency in conjunction with the pixel-processing 
operation and the plane mask is described in the user's guides 
for the TMS34010 and TMS34020.

Use the transp_on function to demonstrate the effect of 
enabling transparency. Use the draw_rect function from the 
Extended Primitives Library to construct a 
background pattern. To show that the background pattern 
is overwritten in the rectangle surrounding each character, 
use the text_out function to draw a line 
of text to the screen with transparency disabled. 
Also, draw a line of text to the screen with transparency 
enabled to show that the background pattern is preserved.

#include  <gsptypes.h>		/* defines FONTINFO structure */

main()
{
    short x, y;
    FONTINFO fntinf;

    set_config(0, !0);
    clear_screen(-1);
    get_fontinfo(-1, &fntinf);
    for (x = y = 0; y < 80; y += 13)
	draw_rect(180, 7, x, y);
    x = y = 10;
    text_out(x, y, "Transparency is off.");
    transp_on();
    text_out(x, y+fntinf.charhigh, "Transparency is on.");
}

void wait_scan(line)
short line;	/* scan line number */

The wait_scan function waits for the monitor to scan a 
designated line on the screen.

Argument line is the scan line number. Scan lines are numbered 
in ascending order, starting with line 0 at the top of the screen. 
Given a display of N lines, valid arguments are in the range 
0 to N-1. If argument line is less than 0, the function uses 
the value 0 in place of the argument value. If argument 
line is greater than the bottom scan line, the function uses 
the number of the bottom scan line in place of the argument value.

The number of scan lines on the screen in the current graphics 
mode is specified in the disp_vres field of the CONFIG 
structure returned by the get_config function.

Once the function is called, it does not return control to the 
calling routine until the designated line is scanned by 
the monitor's electron beam. Control is 
returned at the start of the horizontal blanking 
interval that follows the scan line.

This function is used to synchronize drawing operations 
with the position of the electron beam on the monitor screen. 
For example, when drawing an animated 
sequence of frames, transitions from one frame 
to the next appear smoother if an area of the screen is not being 
drawn at the same time it is being scanned 
on the monitor.

The wait_scan function is typically used to achieve a limited 
degree of smooth animation in graphics modes that provide 
only a single video page (or frame buffer). The page_flip and 
page_busy functions support double buffering in 
modes that provide more than one page. Double buffering, when
available, is usually preferred for animation applications.

Use the wait_scan function to smoothly animate a rotating 
asterisk. The position of the asterisk is updated once per frame. 
Before drawing the asterisk in its updated position, the wait_scan 
function is utilized to delay erasing the asterisk until the area just beneath 
it is being scanned. The asterisk is erased by overwriting 
it with a space character. This technique works well with 
the system font, which is a block font, but might produce 
unexpected results if used with a proportionally spaced font.

#include  <gsptypes.h>		/* defines FONTINFO structure */
#define  RADIUS   60		/* radius of revolution */

main()
{
    long x, y;
    short i, j;
    FONTINFO fntinf;

    set_config(0, !0);
    clear_screen(-1);
    get_fontinfo(-1, &fntinf);
    x = RADIUS << 16;
    y = 0;
    for (i = j = 0; ; ) {
	wait_scan(j+fntinf.charhigh);
	text_out(i, j, " ");
	i = RADIUS + (x >> 16);
	j = RADIUS + (y >> 16);
	text_out(i, j, "*");
	x -= y >> 4;
	y += x >> 4;
    }
}

