The <graph.h> Header File

Common (non-windowed) graphic routines

Functions

BitmapGet
Gets a bitmap from the port graphical functions are writing to.
BitmapInit
Initializes a bitmap structure.
BitmapPut
Puts a bitmap to the screen.
BitmapSize
Determines a bitmap size in bytes.
CalcBitmapSize
Calculates the size of a bitmap.
ClientToScr
Converts a window-based rectangle to screen-based coordinates.
ClrScr
Clears the entire screen.
DisplayOff
Turns the display off.
DisplayOn
Turns the display on.
DrawChar
Draws a character.
DrawClipChar
Draws a clipped character.
DrawClipEllipse
Draws a clipped ellipse.
DrawClipLine
Draws a clipped line.
DrawClipPix
Draws a clipped pixel.
DrawClipRect
Draws a clipped rectangle.
DrawFkey
Draws a function key symbol.
DrawIcon
Draws an icon.
DrawLine
Draws a line between two specified points.
DrawMultiLines
Draws a set of lines in one turn.
DrawPix
Draws a pixel.
DrawStr
Draws a string.
DrawStrWidth
Determines the width of a string, in pixels.
DrawStrWidthP
Returns the width of the first len characters of a string.
FillLines2
Draws a filled area between two lines.
FillTriangle
Draws a filled triangle.
FontCharWidth
Determines the character width in pixels.
FontGetSys
Gets the current font number.
FontSetSys
Sets the current font.
GetPix
Gets the status of a specified pixel.
LCD_restore
Restores the saved content of the LCD screen.
LCD_save
Saves the content of the LCD screen.
LineTo
Draws a clipped line from the current pen position.
MakeScrRect
Puts four coordinates into a SCR_RECT and returns a pointer to it.
MakeWinRect
Builds a structure for representing rectangular area.
MoveTo
Sets the current pen position.
PortRestore
Cancels the virtual screen.
PortSet
Sets up the virtual screen.
QScrRectOverlap
Determines whether two rectangular areas overlap or not.
RestoreScrState
Restores a a saved state of the graphic system.
SaveScrState
Saves the state of the graphic system.
ScrRectFill
Draws a filled rectangle.
ScrRectOverlap
Finds an intersection of two rectangular areas.
ScrRectScroll
Scrols a rectangular area upwards or downwards.
ScrRectShift
Shifts a rectangular area left or right.
ScrToHome
Shifts structure of type SCR_RECT to the home position.
ScrToWin
Converts a structure of type SCR_RECT to type WIN_RECT.
SetCurAttr
Sets the default attribute.
SetCurClip
Sets the default clipping area.
sf_width
Returns the width in pixels of character character in the small font.

Global Variables

ScrRect
A global pointer to a SCR_RECT structure representing the whole screen.

Constants

BITMAP_HDR_SIZE
Defines the size of the header of the BITMAP structure.
LCD_MEM
A pointer to the area in memory where the contents of the LCD screen are stored.
LCD_SIZE
An integer constant which represents the size of the LCD screen in bytes.

Predefined Types

Attrs
An enumeration for describing legal attribute values.
BITMAP
A structure for defining a bitmap.
Bool
An enumeration to describe true or false values.
BoxAttrs
An enumeration for describing addittional box attribute values.
Fonts
An enumeration for describing legal font values.
ICON
A structure which describes an icon.
LCD_BUFFER
Describes a buffer to hold the screen contents.
MULTI_LINE
A structure for defining multiple lines for the DrawMultiLines command.
pICON
A pointer to the ICON scructure.
SCR_COORDS
An alias type for defining physical screen coordinates.
SCR_RECT
A scructure for defining a rectangular area.
SCR_STATE
A structure for saving the state of the graphics system.
WIN_COORDS
An alias type for defining logical screen coordinates.
WIN_RECT
A structure for defining a rectangular area.

For a lot of advanced drawing routines, we recommend you to download the ExtGraph library by the TI-Chess Team.

See also: wingraph.h, sprites.h, gray.h


BitmapGet

void BitmapGet (const SCR_RECT *rect, void *BitMap);

Gets a bitmap from the port graphical functions are writing to.

BitmapGet stores a series of bytes (the size of which is defined by BitmapSize) defining a bitmap for a rectangular area (whose boundaries are given using the SCR_RECT structure rect) into a buffer pointed to by BitMap. The data is fetched in the port graphical functions are writing to (see PortSet). The first two words at the address BitMap will contain the height and the width (in pixels) of the rectangular area respectively, then the actual data follows. BitMap is usually a pointer to a BITMAP structure.

Here is a simple example (called "Bitmap Test"), which uses BitmapGet and BitmapPut to get the contents of the TI-89 screen and to restore it later:

// Retrieve and store a bitmap

#define USE_TI89              // Compile for TI-89
#define USE_TI92PLUS          // Compile for TI-92 Plus
#define USE_V200              // Compile for V200

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization

#define MIN_AMS 100           // Compile for AMS 1.00 or higher

#include <tigcclib.h>         // Include All Header Files

// Main Function
void _main(void)
{
  SCR_RECT full_screen = {{0, 0, LCD_WIDTH - 1, LCD_HEIGHT - 1}};
  char buffer [BITMAP_HDR_SIZE + LCD_WIDTH*LCD_HEIGHT/8]; // or 2004 for a TI-89 and 3844 for a TI-92+/V200 if you like it more
  BitmapGet (&full_screen, buffer);          // store screen in buffer
  clrscr ();
  printf ("Press any key to\nrestore screen...");
  ngetchx ();
  BitmapPut (0, 0, buffer, &full_screen, A_REPLACE);
  ngetchx ();
}

Note that this is just an example: for saving/restoring the whole screen, functions LCD_save and LCD_restore are much more efficient! And, 'buffer' will probably be allocated using malloc in a more realistic example...

See also: BitmapPut, BitmapSize, CalcBitmapSize


BitmapInit

void BitmapInit (const SCR_RECT *rect, void *BitMap);

Initializes a bitmap structure.

BitmapInit is an auxilary command (used internally in BitmapGet, so it is not particularly useful). It initializes first two words at address BitMap to the height and the width (in pixels) of the rectangular area rect.


BitmapPut

void BitmapPut (short x, short y, const void *BitMap, const SCR_RECT *clip, short Attr);

Puts a bitmap to the screen.

BitmapPut puts a bitmap BitMap (which was taken using BitmapGet) on the screen at position (xy), using the attribute Attr. The drawn bitmap will be clipped at the boundaries of the area given by the clip parameter. See SetCurClip for more info about clipping areas. The following attributes are supported:

A_REPLACEReplace the destination region with the source bitmap
A_REVERSEReplace the destination region with the inverse of the source bitmap
A_NORMALOR the source bitmap into the destination region
A_XORExculsive-OR the source bitmap into the destination region
A_OROR the source bitmap into the destination region
A_ANDAND the source bitmap into the destination region
A_SHADEDMask the source bitmap so that every other pixel is turned off and replace the destination region with that result (the source region is left unchanged)

See SetCurAttr command for more general info about attributes.

It seems that the A_REVERSE attribute is broken in current implementations of this function: If the value of x is not a multiple of 8, a black vertical line will appear across the picture.

Note: The sprites.h header file supports much faster alternatives to the BitmapPut function for bitmap shapes which are not wider than 32 pixels (useful for games programming).

See also: BitmapGet, CalcBitmapSize


BitmapSize

unsigned short BitmapSize (const SCR_RECT *rect);

Determines a bitmap size in bytes.

BitmapSize returns the size in bytes of a bitmap for a rectangular area given by parameter rect. This size includes the data for the bitmap and the header. See BitmapGet for more info about bitmaps.

See also: BitmapGet


CalcBitmapSize

AMS 2.00 or higher

unsigned short CalcBitmapSize (BITMAP *b);

Calculates the size of a bitmap.

CalcBitmapSize calculates the size of the bitmap pointed to by b. In fact, CalcBitmapSize has the following implementation:

unsigned short CalcBitmapSize(BITMAP *b)
{
  return ((((b->NumCols + 7) >> 3) * b->NumRows) + BITMAP_HDR_SIZE);
}

This means that you can create a bitmap with only NumRows and NumCols filled, and pass it to this function.

You can also define a macro for this purpose.

See also: BitmapGet, BitmapPut, BitmapSize


ClientToScr

AMS 2.00 or higher

void ClientToScr (const SCR_RECT *WindowRect, const SCR_RECT *Rect, SCR_RECT *Result);

Converts a window-based rectangle to screen-based coordinates.

ClientToScr adds the values of x1 and y1 in WindowRect to all x and y values in Rect, and returns the result in Result. This is usually used to convert a window-based SCR_RECT to screen-based coordinates by passing it as the second parameter to this function. The first parameter is then a screen-based SCR_RECT of the window's client region. This routine is called in SetWinClip.

See also: ScrToWin


ClrScr

void ClrScr (void);

Clears the entire screen.

ClrScr fills the entire screen (real or virtual) with zeros. To set up a virtual screen, use PortSet.

Deprecated alias: ClearScreen


DisplayOff

void DisplayOff (void);

Turns the display off.

DisplayOff turns the display off. It does not really switch the LCD off, it just blanks the screen and keeps it blank. To turn the display back on, you must use DisplayOn.

See also: DisplayOn


DisplayOn

void DisplayOn (void);

Turns the display on.

DisplayOn turns the display on. It is mostly used after you turned the display off using DisplayOff.

See also: DisplayOff


DrawChar

void DrawChar (short x, short y, char c, short Attr);

Draws a character.

DrawChar draws a character c at a specific (xy) location. The following character attributes are supported (the region defined by a character is 8x10 for huge font, 6x8 for large font or nx5 for small font, depending on the current font set by FontSetSys command):

A_NORMALThe character is ORed into the destination
A_REVERSEThe region created by inversing the character replaces the destination
A_REPLACEThe region defined by the character replaces the destination
A_XORThe character is XORed into the destination
A_SHADEDThe character is masked so that every other pixel is turned off then ORed into the destination

See SetCurAttr command for more general info about attributes.


DrawClipChar

void DrawClipChar (short x, short y, short c, const SCR_RECT *clip, short Attr);

Draws a clipped character.

DrawClipChar works exactly like DrawChar, except the character will be clipped at the boundaries of the area given by parameter clip. See SetCurClip for more info about clipping areas.


DrawClipEllipse

void DrawClipEllipse (short x, short y, short a, short b, const SCR_RECT *clip, short Attr);

Draws a clipped ellipse.

DrawClipEllipse draws an ellipse with centre at (xy), and with semiaxes a and b. The ellipse will be clipped at the boundaries of the area given by parameter clip. See SetCurClip for more info about clipping areas. The interior of the ellipse remains intact (no fill). The ellipse will be drawn using the attribute Attr. Supported attributes are:

A_NORMALDraw a elipse
A_REVERSEErase a ellipse
A_XORXORs a ellipse into the destination

See SetCurAttr for more general information about attributes.

Note: Set a== b to draw a circle.


DrawClipLine

void DrawClipLine (const WIN_RECT *Line, const SCR_RECT *clip, short Attr);

Draws a clipped line.

DrawClipLine draws a line from (x0, y0) to (x1, y1) where coordinates (x0, y0) and (x1, y1) are given in a WIN_RECT structure Line, using the attribute Attr. The line will be clipped at the boundaries of the area given by parameter clip. See SetCurClip for more info about clipping areas. See DrawLine for a description of supported atributes.


DrawClipPix

void DrawClipPix (short x, short y);

Draws a clipped pixel.

DrawClipPix works exactly like DrawPix, except the pixel will not be drawn if its coordinates are out of clipping zone given by SetCurClip command, and an attribute is not given as an explicite parameter (the attribute given with SetCurAttr command will be used instead).


DrawClipRect

void DrawClipRect (const WIN_RECT *rect, const SCR_RECT *clip, short Attr);

Draws a clipped rectangle.

DrawClipRect draws a rectangle with (x0, y0) and (x1, y1) as corners, where coordinates (x0, y0) and (x1, y1) are given in a WIN_RECT structure rect. The rectangle will be clipped at the boundaries of the area given by parameter clip. See SetCurClip for more info about clipping areas. The interior of the rectangle remains intact (no fill). The border lines of the rectangle will be drawn using the attribute Attr. See DrawLine for a description of supported line atributes. In addition, the attribute may be ORed with one or more following constants (which are defined in enum BoxAttrs:

B_NORMALDraw a normal rectangle
B_DOUBLEDraw a double thick rectangle
B_ROUNDEDDraw a rectangle with rounded corners
B_CUTDraw a rectangle with the upper corners cut (like in toolboxes)

Note: I cannot conclude what the difference is if you OR the attribute with B_NORMAL or if you do not do so. Maybe I am stupid.


DrawFkey

void DrawFkey (short x, short y, short fkey_no, short Attr);

Draws a function key symbol.

DrawFkey draws a string "F<fkey_no>" at (xy), using the attribute Attr, and using small font, regardless of the current font setting. See DrawChar for a description of attribute Attr. fkey_no must be in a range 0-9.


DrawIcon

void DrawIcon (short x, short y, const void *Icon, short Attr);

Draws an icon.

DrawIcon draws an icon (a 16x16 bitmap structure given as 16-word group of bits) pointed to by pointer Icon at location (xy) using attribute Attr. Pointer Icon is usually of type pICON (pointer to the ICON structure). The following attributes are supported:

A_NORMALThe icon is ORed into the destination
A_REVERSEThe inversed icon is ANDed into the destination
A_XORThe icon is XORed into the destination
A_SHADEDThe icon is masked so that every other pixel is turned off then ORed into the destination

See SetCurAttr command for more general info about attributes.

Note: In antediluvian releases of TIGCCLIB (before 2.0) the documentation said that A_REPLACE attribute is supported. Unfortunately, it seems that this is not true (Daniel Pineo informed me about this problem). Also, information about usage of A_REVERSE was incorrect.

See also: sprites.h


DrawLine

void DrawLine (short x0, short y0, short x1, short y1, short Attr);

Draws a line between two specified points.

DrawLine draws a line from (x0y0) to (x1y1) using the attribute Attr. The following attributes are supported:

A_NORMALDraw a normal line
A_REVERSEDraw an inverse line (i.e. erase the line)
A_XORDraw a line using XORing with the destination
A_THICK1Draw a double thick line
A_SHADE_VDraw the line using a vertical shading pattern
A_SHADE_HDraw the line using a horizontal shading pattern
A_SHADE_NSDraw the line using a negative slope diagonal shading pattern
A_SHADE_PSDraw the line using a positive slope diagonal shading pattern

See SetCurAttr command for more general info about attributes. Note that although TI said nothing about it, attributes A_SHADE_V, A_SHADE_H, A_SHADE_NS and A_SHADE_PS work only for lines with slope more than 45 degree (i.e. for lines which are more "vertical" than "horizontal"). For "nearly horizontal" lines all of them act like A_NORMAL. I don't know whether it is a bug, or planned feature. So, if you want to draw shaded-fill rectangle using DrawLine in a loop, use vertical lines for drawing, not horizontal ones!

Using DrawLine (and all other graphic comands which does not do clipping) may be harmful if called using parameters which are out of legal range (i.e. out of the screen area).


DrawMultiLines

void DrawMultiLines (short x, short y, const void *multi_lines);

Draws a set of lines in one turn.

DrawMultiLines draws a whole set of lines using a single command. The parameter multi_lines is a pointer to the byte-area structure organized as follows:

The line will be clipped at the current clipping area boundaries given with SetCurClip command. multi_lines is usually a pointer to the MULTI_LINE structure. See DrawLine for more info about line attributes.

Parameters x and y act as a translation shifters. They are added to all line coordinates before drawing (the structure itself remains intact), so by using the same multi_line with various x-s and y-s, it is possible to draw several instances of the same-shape objects on various places on the screen.

The following example will draw two stars on the screen:

static MULTI_LINE star_shape = {3, {{1, 30, 50, 70, 50},
                                    {1, 35, 35, 65, 65},
                                    {1, 35, 65, 65, 35}}};
...
DrawMultiLines (0, 0, &star_shape);
DrawMultiLines (80, 0, &star_shape);

DrawPix

void DrawPix (short x, short y, short Attr);

Draws a pixel.

DrawPix draws a pixel at (xy), using the attribute Attr. The following attributes are supported:

A_NORMALDraw a pixel
A_REVERSEErase a pixel
A_XORInvert a pixel

See SetCurAttr command for a more general info about attributes.


DrawStr

void DrawStr (short x, short y, const char *str, short Attr);

Draws a string.

DrawStr draws a string str at a specific (xy) location. See DrawChar for a description of attribute Attr.

Note: Too many people ask me how to draw a content of an integer variable (for example) instead of a string. Although this question is answered in the Frequently Asked Question list, I received a suggestion that it would be better if explained here. Well. You need to use sprintf to convert a non-string variable to a string. For example:

int x, y;
char buffer[50];
...
sprintf (buffer, "%d + %d = %d", x, y, x + y);
DrawStr (0, 0, buffer, A_NORMAL);

Deprecated alias: DrawStrXY


DrawStrWidth

short DrawStrWidth (const char *str, short Font);

Determines the width of a string, in pixels.

DrawStrWidth returns the actual width of the string str according to the font number given by parameter Font. For 8x10 and 6x8 fonts, this is just 8 or 6 times the length of the string, but the 4x6 font is proportional. See FontSetSys for more info on fonts.

See also: DrawStrWidthP


DrawStrWidthP

AMS 2.00 or higher

unsigned short DrawStrWidthP (const char *str, short len, short Font);

Returns the width of the first len characters of a string.

DrawStrWidthP returns the length in pixels of the first len characters of the string str displayed with font Font. The difference between DrawStrWidthP and DrawStrWidth is that DrawStrWidth gives the length in pixels of the full string str displayed with font Font.
Be careful: len must be less or equal to strlen (str)!

This function is interesting only for the F_4x6 font; for the F_6x8 and F_8x10 fonts, DrawStrWidthP will return 6*len and 8*len, respectively. Also, using

DrawStrWidthP (str, strlen (str), font);

is slower than using

DrawStrWidth (str, font);

Example:

// This line is equivalent to:
// printf_xy (0, 0, "%hu", DrawStrWidth ("DEFGHIJK", F_4x6));
printf_xy (0, 0, "%hu",
  DrawStrWidthP ("ABCDEFGHIJKLMNOPQRSTUVWXYZ" + 3, 8, F_4x6));

On AMS versions lower than 2.00, you can emulate DrawStrWidthP with:

unsigned short DrawStrWidthP(const char *str, short len, short Font)
{
  char s[len+1];
  short i;
  // Calling memcpy is slower than copying the string by-hand...
  for (i = 0; i < len; i++)
    s[i] = str[i];
  s[len] = 0;
  return DrawStrWidth (s, font);
}

or the following assembly code provided by Lionel Debroux:

unsigned short DrawStrWidthP(register const char *str asm("a0"), register short len asm("d0"), register short Font asm("d2"));
asm("DrawStrWidthP:
    move.w   %d0,%d1
    beq.s    __end_DrawStrWidthP__
    btst     #0,%d0
    beq.s    __allocate_on_the_stack_DSWP__
    addq.w   #1,%d1
__allocate_on_the_stack_DSWP__:
    suba.w   %d1,%sp
    
    movea.l  %sp,%a1
    subq.w   #1,%d0
__loop_copy_DrawStrWidthP__:
    move.b   (%a0)+,(%a1)+
    dbf      %d0,__loop_copy_DrawStrWidthP__
    clr.b    (%a1)
    
    addq.w   #8,%d1
    move.w   %d1,-(%sp) | save d1 (DrawStrWidth can destroy it)...
    move.w   %d2,-(%sp)
    pea      4(%sp)
    movea.l  0xC8.w,%a0
    movea.l  0x197*4(%a0),%a0 | DrawStrWidth
    jsr      (%a0)
    
    adda.w   6(%sp),%sp
__end_DrawStrWidthP__:
    rts
");
 

The C function is about 1% slower than the original implementation. The assembly implementation is faster.

See also: DrawStrWidth


FillLines2

void FillLines2 (const WIN_RECT *lower_line, const WIN_RECT *upper_line, const SCR_RECT *clip, short Attr);

Draws a filled area between two lines.

FillLines2 fills an area bounded with two lines which coordinates are given in two WIN_RECT structures lower_line (lower bound) and upper_line (upper bound). In fact, it draws a filled polygon whose vertices are (lower_line.x0, lower_line.y0), (lower_line.x1, lower_line.y1), (upper_line.x0, upper_line.y0) and (upper_line.x1, upper_line.y1) using the attribute Attr. Supported attributes are the same as in command FillTriangle. The drawn polygon will be clipped at the boundaries of the area given by parameter clip. See SetCurClip for more info about clipping areas. If lower_line is above upper_line, nothing will be drawn. To be more precise, "above" means "closer to the top of the screen".


FillTriangle

void FillTriangle (short x0, short y0, short x1, short y1, short x2, short y2, const SCR_RECT *clip, short Attr);

Draws a filled triangle.

FillTriangle draws a filled triangle with vertices (x0y0), (x1y1) and (x2y2) using the attribute Attr. The triangle will be clipped at the boundaries of the area given by parameter clip. See SetCurClip for more info about clipping areas. Supported attributes are:

A_NORMALDraws a solid fill triangle
A_REVERSEDraws an empty triangle (i.e. erase a triangular area)
A_XORXORs a solid fill triangle into the destination
A_SHADE_VDraws a triangle filled using a vertical shading pattern
A_SHADE_HDraws a triangle filled using a horizontal shading pattern
A_SHADE_NSDraws a triangle filled using a negative slope diagonal shading pattern
A_SHADE_PSDraws a triangle filled using a positive slope diagonal shading pattern

See SetCurAttr command for more general info about attributes.


FontCharWidth

short FontCharWidth (short c);

Determines the character width in pixels.

FontCharWidth returns the actual width of the character c according to current font settings.

See also: DrawStrWidth


FontGetSys

unsigned char FontGetSys(void);

Gets the current font number.

FontGetSys returns the current font number. See FontSetSys for more info.


FontSetSys

unsigned char FontSetSys (short Font);

Sets the current font.

FontSetSys changes the current text font. All subsequent characters written to the screen will use this font. The supported values for Font are F_4x6, F_6x8, and F_8x10, and they are defined in enum Fonts. The 4x6 font is a proportional font while the 6x8 and 8x10 fonts are fixed-width. FontSetSys returns the previously active font number.


GetPix

short GetPix (short x, short y);

Gets the status of a specified pixel.

GetPix gets the status of the pixel located at (xy). Returns TRUE or FALSE depending on whether the corresponding pixel is set or reset.


LCD_restore

void LCD_restore (const void *buffer);

Restores the saved content of the LCD screen.

LCD_restore restores the contents of the screen (saved using LCD_save) from the buffer pointed to by buffer. buffer is usually of type LCD_BUFFER. LCD_restore is a small macro which calls the memcpy function.

Note: LCD_save and LCD_restore do not work in grayscale mode.


LCD_save

void LCD_save (void *buffer);

Saves the content of the LCD screen.

LCD_save saves the complete contents of the screen into the 3840-bytes long buffer pointed to by buffer. buffer is usually of type LCD_BUFFER. LCD_save is a small macro which calls the memcpy function.

Note: LCD_save and LCD_restore do not work in grayscale mode.


LineTo

void LineTo (short x, short y);

Draws a clipped line from the current pen position.

LineTo draws a line from the current pen position to the pixel (xy) using the current attribute given with SetCurAttr command, then updates the pen position to those coordinates. The line will be clipped at the current clipping area boundaries given with SetCurClip command.

Deprecated alias: DrawTo


MakeScrRect

AMS 2.00 or higher

SCR_RECT *MakeScrRect (short x0, short y0, short x1, short y1, SCR_RECT *s);

Puts four coordinates into a SCR_RECT and returns a pointer to it.

MakeScrRect is used to create a SCR_RECT from four screen coordinates.

For example, it can be used to convert a WIN_RECT to a SCR_RECT like this (s is a SCR_RECT, and rect is a WIN_RECT):

MakeScrRect (rect.x0, rect.y0, rect.x1, rect.y1, &s);

In GNU C (like GCC4TI is), it is generally faster to use cast constructors instead of calling MakeScrRect:

s = (SCR_RECT){{x0, y0, x1, y1}};

See also: SetWinClip, MakeWinRect


MoveTo

void MoveTo (short x, short y);

Sets the current pen position.

MoveTo sets the current pen position to (xy).


PortRestore

void PortRestore (void);

Cancels the virtual screen.

PortRestore restores factory defaults for address and dimensions of the video memory. PortRestore acts exactly like

PortSet ((void *) 0x4C00, 239, 127);

PortSet

void PortSet (void *vm_addr, short x_max, short y_max);

Sets up the virtual screen.

PortSet allows drawing in a virtual screen. All graphic commands which are built-in into TIOS does not expect that the video memory must be at 0x4C00, and that the video memory is always 240 x 128 pixels. Using PortSet you can set up a virtual screen anywhere in a memory, and of any size. After using PortSet, all graphic commands will assume that the video memory starts at vm_addr, and that the dimensions of the video memory are (x_max+1) x (y_max+1) pixels. This allows to you to use graphic functions even when the actual LCD memory is relocated at any other address using I/O hardware ports, or to draw pictures into virtual screens (not visible on the real screen), then move them (using memcpy or some other function) to the real screen. This will enable the possibility of hiding the actual drawing process, and to display the drawn picture immediately.

Here is a code fragment which ilustrates the usage of virtual screens:

void *virtual=malloc (LCD_SIZE);  // Allocate the buffer
...
if (!virtual) ... // do some error handling - not enough memory!
PortSet (virtual, 239, 127); // redirect drawing routines to buffer

or, even simpler, a virtual screen may simply be in any local variable which is long enough:

char virtual[LCD_SIZE];
...
PortSet (virtual, 239, 127);

Note that, in this case, virtual screen memory will in fact be somewhere on the stack. There is nothing bad in this, but keep in mind that the total amount of the stack is 16K, so don't put too much data (like big arrays etc.) on the stack (i.e. in local variables). If you really need to handle a lot of data, use malloc instead.

After setting up the virtual screen, you can do any drawing you want - it will be redirected to the virtual screen. To copy this to the regular screen (i.e. to display it) do this:

memcpy (LCD_MEM, virtual, LCD_SIZE);

or even simpler (this is the same):

LCD_restore (virtual);

Note: Don't forget to do PortRestore before the end of the program, otherwise TIOS will be fooled after returning to TI-Basic!


QScrRectOverlap

short QScrRectOverlap (const SCR_RECT *r1, const SCR_RECT *r2);

Determines whether two rectangular areas overlap or not.

QScrRectOverlap returns TRUE or FALSE depending on whether two rectangular areas given in two SCR_RECT structures r1 and r2 overlap or not.


RestoreScrState

void RestoreScrState (const void *buffer);

Restores a a saved state of the graphic system.

RestoreScrState restores a saved state of the graphic system (saved using SaveScrState command) from a structure pointed to by buffer.


SaveScrState

void SaveScrState (void *buffer);

Saves the state of the graphic system.

SaveStrState saves the current state of the graphic system (including the address and dimensions of the virtual screen, current font, attribute, clipping area and pen position) into a 18-byte structure pointed to by buffer. buffer is usually a pointer to a SCR_STATE structure.


ScrRectFill

void ScrRectFill (const SCR_RECT *rect, const SCR_RECT *clip, short Attr);

Draws a filled rectangle.

ScrRectFill draws a filled rectangle given by SCR_RECT structure rect, using the attribute Attr. The rectangle will be clipped at the boundaries of the area given by parameter clip. See SetCurClip for more info about clipping areas. Supported attributes are:

A_NORMALFill with black pixels
A_REVERSEFill with white pixels
A_XORAll pixels in the rectangle will be reversed

FillLines2 is more complicated and slower function than ScrRectFill, but it supports many more attributes. See SetCurAttr for more info about attributes.

Note: TI said that attribute A_SHADED (set to a pattern of pixels on and off) is also supported, but it didn't work when I tried it; at least, it does not work on AMS 1.00.


ScrRectOverlap

short ScrRectOverlap (const SCR_RECT *r1, const SCR_RECT *r2, SCR_RECT *r);

Finds an intersection of two rectangular areas.

ScrRectOverlap finds an intersection of two rectangular areas given in two SCR_RECT structures r1 and r2, and stores coordinates of the intersection in r. ScrRectOverlap returns TRUE or FALSE depending on whether r1 and r2 overlap or not.


ScrRectScroll

void ScrRectScroll (const SCR_RECT *rect, const SCR_RECT *clip, short NumRows, short Attr);

Scrols a rectangular area upwards or downwards.

ScrRectScroll scrolls a rectangular area which is an intersection of two rectangular areas given using two SCR_RECT structures rect and clip upwards by NumRows pixels (or downwards if NumRows < 0). rect usually represents the actual area which need to be scrolled, and clip is the clipping area. See SetCurClip for more info about clipping areas. The attribute Attr determines what happens with pixels in a vacant space produced after scrolling:

A_NORMALPixels in a vacant space are set
A_REVERSEPixels in a vacant space are reset
A_XORPixels in a vacant space are inverted

See SetCurAttr command for more general info about attributes.

Note: This command is internally realized stupidly using BitmapGet and BitmapPut, so it is slow.


ScrRectShift

void ScrRectShift (const SCR_RECT *rect, const SCR_RECT *clip, short NumCols, short Attr);

Shifts a rectangular area left or right.

ScrRectShift shifts a rectangular area which is an intersection of two rectangular areas given using two SCR_RECT structures rect and clip left by NumRows pixels (or right if NumRows < 0). The attribute Attr determines what happens with pixels in a vacant space produced after shifting. For more info, see ScrRectScroll command.


ScrToHome

SCR_RECT *ScrToHome (SCR_RECT *rect);

Shifts structure of type SCR_RECT to the home position.

ScrToHome modifies the structure pointed to by rect so that the modified structure will represent the same-shape rectangular area, but with topleft corner at position (0, 0). ScrToHome returns rect back (but note that the structure pointed to by it is modified).


ScrToWin

WIN_RECT *ScrToWin (const SCR_RECT *rect);

Converts a structure of type SCR_RECT to type WIN_RECT.

ScrToWin accepts a pointer rect to the structure of type SCR_RECT and returns a static pointer to a structure of type WIN_RECT which represents the same rectangular area. It is stored at a fixed place in memory, which means that you cannot write something like:

foo (ScrToWin (&r1), ScrToWin (&r2));

SetCurAttr

short SetCurAttr (short Attr);

Sets the default attribute.

SetCurAttr sets the default attribute for all commands which haven't an attribute as an explicite parameter to Attr. The interpretation of the attribute depends of concrete graphic command. Some attributes are only valid for certain graphic operation. Legal attribute values are defined in enum Attrs. In a general, the following attributes are supported:

A_REVERSEDestination pixels turned off
A_NORMALDestination pixels turned on
A_XORSource pixels XORed with destination pixels
A_SHADEDDestination pixels masked so that every other pixel turned off
A_REPLACESource pixels replace destination pixels
A_ORSource pixels ORed with destination pixels

For lines the following additional attributes are supported:

A_THICK1Draw a double thick line
A_SHADE_VDraw the line using a vertical shading pattern
A_SHADE_HDraw the line using a horizontal shading pattern
A_SHADE_NSDraw the line using a negative slope diagonal shading pattern
A_SHADE_PSDraw the line using a positive slope diagonal shading pattern

SetCurAttr returns the previous current attribute.

Note: Although TI said nothing about it, attributes A_SHADE_V, A_SHADE_H, A_SHADE_NS and A_SHADE_PS work only for lines with slope more than 45 degree (i.e. for lines which are more "vertical" than "horizontal"). For "nearly horizontal" lines all of them act like A_NORMAL. I don't know whether it is a bug, or planned feature. So, if you want to draw shaded-fill rectangle using a line drawing command (for example, DrawLine) in a loop, use vertical lines for drawing, not horizontal ones! Note also that these additional attributes work fine with FillTriangle and FillLines2, but not with ScrRectFill!


SetCurClip

void SetCurClip (const SCR_RECT *clip);

Sets the default clipping area.

SetCurClip sets the default clipping area for commands which are sensitive to clipping, but which do not need a clipping area as an explicit parameter (such commands are LineTo and DrawClipPix). The clipping area is a rectangle with corners (x0, y0) and (x1, y1) which is given using a SCR_RECT structure clip. All clip-sensitive drawings will be clipped (truncated) at the current clipping area boundaries. Be warned: the default clipping area at the beginning of the program is not the full screen!

Note: GCC4TI is GNU C, so it allows cast constructors. That's why constructions like

SetCurClip (&(SCR_RECT){{0, 0, 159, 99}});

are legal.


sf_width

AMS 2.00 or higher

unsigned char sf_width(unsigned char character);

Returns the width in pixels of character character in the small font.

See also: DrawStrWidth, DrawStrWidthP, FontCharWidth


ScrRect

SCR_RECT *const ScrRect;

A global pointer to a SCR_RECT structure representing the whole screen.

ScrRect is a (constant) pointer to a SCR_RECT structure set by TIOS to point to a structure which represents the whole screen area without the status line. So, if you don't need drawing in the status line, you can set the default clipping area using the SetCurClip command like

SetCurClip (ScrRect);

or, you can use ScrRect in a command which needs clipping area parameter explicitely (such command is DrawClipEllipse, for example):

DrawClipEllipse (50, 50, 30, 20, ScrRect, A_NORMAL);

ScrRect may be used also to determine a calculator type. If

ScrRect->xy.x1 == 159

then the calculator is a TI-89 or TI-89 Titanium, else it is a TI-92 Plus or V200.

Note: ScrRect is a variable, so it may be changed (more precise, the structure on which it points may be changed). By changing it, it is possible to force some TIOS commands which normally cannot access to the status line area to get the access to this "forbidden" zone, or to force some commands to use only smaller part of the screen. Use this possibility with great care, and only if you know exactly what you are doing!


BITMAP_HDR_SIZE

#define BITMAP_HDR_SIZE 4

Defines the size of the header of the BITMAP structure.


LCD_MEM

#define LCD_MEM ((void *) 0x4C00)

A pointer to the area in memory where the contents of the LCD screen are stored.

See also: LCD_SIZE, LCD_BUFFER


LCD_SIZE

#define LCD_SIZE 3840

An integer constant which represents the size of the LCD screen in bytes.

See also: LCD_MEM, LCD_BUFFER


Attrs

enum Attrs {A_REVERSE, A_NORMAL, A_XOR, A_SHADED, A_REPLACE, A_OR, A_AND, A_THICK1, A_SHADE_V, A_SHADE_H, A_SHADE_NS, A_SHADE_PS};

An enumeration for describing legal attribute values.

For more information about attributes, see the SetCurAttr command or the GR_WIN_VARS structure.

See also: SetCurAttr, GR_WIN_VARS, WinAttr, WinFillTriangle, ScrRectScroll, ScrRectFill, FillTriangle, DrawPix, DrawClipEllipse, DrawIcon, WinPixSet, DrawChar, WinBackground, WinEllipse, WinFill, BitmapPut, WinChar


BITMAP

typedef struct {
unsigned short NumRows, NumCols;
unsigned char Data[];
} BITMAP;

A structure for defining a bitmap.

BITMAP is a structure for defining a bitmap, used in commands like BitmapGet.

Note that Data[] is a GNU C extension for variable-length arrays (GCC4TI is GNU C).


BoxAttrs

enum BoxAttrs {B_NORMAL = 0x10, B_ROUNDED = 0x20, B_DOUBLE = 0x40, B_CUT = 0x80};

An enumeration for describing addittional box attribute values.

For more info about box attributes, see the DrawClipRect command.


Fonts

enum Fonts {F_4x6, F_6x8, F_8x10};

An enumeration for describing legal font values.

For more info about fonts, see FontSetSys.


ICON

typedef struct {
unsigned short i[16];
} ICON;

A structure which describes an icon.

ICON is a structure which describes an icon (a 16x16 pixel area), which is used in the DrawIcon command.


LCD_BUFFER

typedef char LCD_BUFFER[LCD_SIZE];

Describes a buffer to hold the screen contents.

LCD_BUFFER is a 3840-bytes long array type. Its main purpose is to declare a buffer for saving and restoring the contents of the LCD screen using the functions LCD_save and LCD_restore.

It is long enough to accept the content of the screen on both the TI-89 and the TI-92 Plus.

See also: LCD_MEM, LCD_SIZE


MULTI_LINE

typedef struct {
unsigned char Count;
struct {
signed char Attr, x0, y0, x1, y1;
} Data[];
} MULTI_LINE;

A structure for defining multiple lines for the DrawMultiLines command.

Note that Data[] is a GNU C extension for variable-length arrays (GCC4TI is GNU C). Static variables of such types may be initialized with a variable-length constructor, for example:

static MULTI_LINE star_shape = {3, {{1, 30, 50, 70, 50},
                                    {1, 35, 35, 65, 65},
                                    {1, 35, 65, 65, 35}}};

Initialization with a variable-length constructor is not suitable for non-static (auto) variables, because the amount of stack storage will not be determined properly.


pICON

typedef unsigned short *pICON;

A pointer to the ICON scructure.


SCR_COORDS

typedef unsigned char SCR_COORDS;

An alias type for defining physical screen coordinates.


SCR_RECT

typedef union {
struct {
unsigned char x0, y0, x1, y1;
} xy;
unsigned long l;
} SCR_RECT;

A scructure for defining a rectangular area.

SCR_RECT is a structure (more precisely, an union) for defining a rectangular area using physical screen coordinates.

Instead of giving four coordinates x0, y0, x1 and y1, it is possible to give all together using a field l which is a packed long number.

Note: GCC4TI is derived from GNU C, so it allows cast constructors. That's why, constructions like

DrawClipEllipse (50, 50, 30, 20, &(SCR_RECT){{0, 0, 159, 99}}, A_NORMAL);

are legal. See DrawClipEllipse for info about this command.

See also: ScrRect


SCR_STATE

typedef struct {
void *ScrAddr;
unsigned char XMax, YMax;
short CurFont, CurAttr, CurX, CurY;
SCR_RECT CurClip;
} SCR_STATE;

A structure for saving the state of the graphics system.

SCR_STATE is a structure used for saving the state of the graphics system, used in the commands SaveScrState and RestoreScrState.


Return to the main index