VSA256 Graphics Library For C Programmers Version 1.1 June 30, 1992 Copyright Spyro Gumas, 1992. All Rights Reserved VESA256 Graphics Library for C Programmers June 30, 1992 Version 1.1 1.0 Introduction 3 2.0 The Programming Environment 4 2.1 Setting Up The VESA Environment 4 2.2 Global Graphics Parameters 4 3.0 Function Descriptions 5 3.1 VESA Configuration Functions 5 3.1.1 vsa_set_svga_mode 5 3.1.2 vsa_get_svga_mode 6 3.1.3 vsa_init 6 3.2 Miscellaneous Functions 7 3.2.1 vsa_set_display_start 7 3.2.2 vsa_get_display_start 7 3.3 Attribute Functions 8 3.3.1 vsa_set_color 8 3.3.2 vsa_set_text_color 8 3.4 Color Look Up Table Functions 9 3.4.1 vsa_read_color_register 9 3.4.2 vsa_write_color_register 9 3.4.3 vsa_read_color_block 10 3.4.4 vsa_write_color_block 10 3.5 Text Functions 11 3.5.1 vsa_set_text_cursor 11 3.5.2 vsa_set_text_cursor_mode 11 3.5.3 vsa_write_char 11 3.5.4 vsa_write_string 12 3.5.5 vsa_write_string_alt 12 3.6 Basic Drawing Functions 12 3.6.1 vsa_move_to 12 3.6.2 vsa_set_pixel 13 3.6.3 vsa_line_to 13 3.6.4 vsa_rect_fill 13 3.6.5 vsa_rect 13 3.6.6 vsa_h_line 14 3.6.7 vsa_v_line 14 3.7 Specialized Drawing Functions 14 3.7.1 vsa_raster_line 14 4.0 Nitty Gritties 15 4.1 Registration Information 15 4.2 Software License 15 4.3 Disclaimer 15 4.4 Technical Support 16 5.0 Coming Attractions 17 5.1 Graphics Library Extensions 17 6.0 Appendix 18 6.1 VSA.H Include File 18 Page: 2 VESA256 Graphics Library for C Programmers June 30, 1992 Version 1.1 1.0 Introduction The Video Electronics Standards Association (VESA) has developed a set of BIOS extensions which standardize the Super VGA (SVGA) graphics environment. The VSA256 Graphics Library provides a C programmer with the tools necessary to drive a video adapter running with the VESA version 2.0 BIOS extensions. The name "VSA256" reflects the fact that this library is primarily aimed at supporting the 256 color video modes 100h, 101h, 103h, 105h, and 107h defined within the VESA standard (See table in section 3.1.1). This is a revision to the original shareware version of VSA256 Graphics Library. The major changes are listed below: - One library for all memory models - Support for Borland C as well as Microsoft C - New routine, vsa_set_text_cursor - New routine, vsa_set_text_cursor_mode - New routine, vsa_write_string_alt The distribution of the VSA256 Graphics Library consists of the 7 files listed below plus the drivers listed in Section 2.1. These files are archived in the self extracting file VSA256.EXE. To extract, just type VSA256 in the directory that you want the files extracted to. When distributing the VSA256 Graphics Library, distribute VSA256.EXE instead of the individual files. VSA_DEMO.C Demonstration program (Source Code). VSA_DEMO.EXE Demonstration program (Executable). VSA256MS.LIB VSA256 Graphics Library (Microsoft C compatible). VSA256BC.LIB VSA256 Graphics Library (Borland C Compatible). VSA.H Include file required in your program. VSA256.TXT This text document. ORDER.TXT A text file order form for upgrades and registration. Page: 3 VESA256 Graphics Library for C Programmers June 30, 1992 Version 1.1 2.0 The Programming Environment 2.1 Setting Up The VESA Environment The VSA256 Graphics Library works with any (any?) IBM PC, XT, AT or compatible computer equipped with an SVGA video adapter card capable of 256 colors. A math coprocessor chip is not required, however if it exists, this library will take advantage of it. Before using the VSA256 Graphics Library, the VESA BIOS Extensions must be loaded. This is accomplished by executing the appropriate driver or adding it to your AUTOEXEC.BAT file. If your video adapter card came with a VESA driver, use it. Otherwise use one of the drivers provided depending on the video adapter card installed in the PC as follows: APPIAN \APPIAN\APVESA.EXE ATI \ATI\VESA.COM C&T \C&T\VESA451.COM (or VESA452.COM) CIRRUS \CIRRUS\CRUSVESA.COM EVEREX \EVEREX\EVRXVESA.COM GENOA \GENOA\VESA.COM OAK \OAK\37VESA.COM (or67VESA.COM) ORCHID \ORCHID\ORCHDVSA.COM PARADISE \PARADISE\VESA.EXE SIGMA \SIGMA\SIGVESA.COM STB \STB\STB-VESA.COM TECMAR \TECMAR\VGAVESA.COM TRIDENT \TRIDENT\VESA.EXE VIDEO7 \VIDEO7\V7VESA.COM 2.2 Global Graphics Parameters The file VSA.H is used as an include file during program development. This file includes all of the function prototypes and it defines the global graphics parameters that describe the specific video adapter installed in the PC (See Section 6.1). The global graphics parameters are initialized by the vsa_init function and are described below: XResolution: Unsigned, the number of screen pixels across (x dimension). YResolution: Unsigned, the number of screen pixels high (y dimension). XCharResolution:Unsigned, the number of screen characters across (x dimension). YCharResolution:Unsigned, the number of screen characters high (y dimension). XCharSize: Unsigned char, the character cell width. YCharSize: Unsigned char, the character cell height. BitsPerPixel: Unsigned char, the number of bits per pixel. Page: 4 VESA256 Graphics Library for C Programmers June 30, 1992 Version 1.1 3.0 Function Descriptions This section describes the functions supported in the VSA256 Graphics Library. To use these functions, link your program with the appropriate library listed below depending on the compiler being used. Borland C++ or Turbo C - VSA256BC.LIB Microsoft C or Quick C - VSA256MS.LIB In the following sections each function is listed along with a definition of its inputs and return values. A description is provided followed by comments on the compatibility of the function with various video modes. Although many functions can drive non-VESA and non-256 color video modes, predictable operation requires that this software be used with the 256 color VESA modes only. 3.1 VESA Configuration Functions 3.1.1 vsa_set_svga_mode(video_mode) Inputs: unsigned video_mode; Returns: unsigned fail_flag; Description: This routine sets the video mode. The mode number may be any of the standard VESA SVGA mode numbers as defined in the tables below. The mode is passed to this routine through the 'video_mode' parameter. This routine returns a 'fail_flag' = 0 if the call was a success (a 1 for failure). It should be noted that this routine will also work with standard MDA, CGA, EGA, and VGA mode numbers, however the rest of the VSA256 functions will not necessarily work. Comments: Works in all VESA video modes. Also works in MDA, CGA, EGA and VGA Modes. WARNING: Use vsa_init Instead (Section 3.1.3)! If you don't use vsa_int, then the rest of the routines won't work because they depend on the global parameters initialized by vsa_init; Page: 5 VESA256 Graphics Library for C Programmers June 30, 1992 Version 1.1 VESA SVGA VIDEO MODES GRAPHICS Mode Resolution Colors 100h 640x400 256 101h 640x480 256 102h 800x600 16 103h 800x600 256 104h 1024x768 16 105h 1024x768 256 106h 1280x1024 16 107h 1280x1024 256 TEXT Mode Columns Rows 108h 80 60 109h 132 25 10Ah 132 43 10Bh 132 50 10Ch 132 60 3.1.2 vsa_get_svga_mode(video_mode) Inputs: unsigned *video_mode; Returns: unsigned fail_flag; Description: This routine gets the current video mode. The mode is returned to the calling routine via the 'video_mode' pointer. The mode number may be any of the standard VESA SVGA mode numbers as defined in Section 3.1.1. This routine returns a 'fail_flag' = 0 if the call was a success (a 1 for failure). Comments: Works in all VESA video modes. Also works in MDA, CGA, EGA and VGA Modes. 3.1.3 vsa_init(video_mode) Inputs: unsigned video_mode; Returns: unsigned fail_flag; Description: This routine sets the video mode and initializes the VESA graphics environment. This routine must be called prior to the use of any of the routines in Sections 3.4 through 3.7. The mode number may be any of the standard VESA SVGA mode numbers as defined in Section 3.1.1. If the mode number is not a VESA SVGA mode number, this routine will still set the desired video mode, however, the VESA graphics environment will not be initialized and subsequent calls to drawing routines will produce unpredictable results. The mode is passed to this Page: 6 VESA256 Graphics Library for C Programmers June 30, 1992 Version 1.1 routine through the 'video_mode' parameter. This routine returns a 'fail_flag' = 0 if the call was a success (a 1 for failure). Comments: Works in all VESA video modes. Also works in MDA, CGA, EGA and VGA Modes. 3.2 Miscellaneous Functions 3.2.1 vsa_set_display_start(x_strt,y_strt) Inputs: unsigned x_strt,y_strt; Returns: unsigned fail_flag; Description: This routine sets the current start pixel address which is mapped to the upper left corner of the display. This routine returns a 'fail_flag' = 0 if the call was a success (a 1 for failure). Comments: Works in all VESA video modes. Also works in MDA, CGA, EGA and VGA Modes. 3.2.2 vsa_get_display_start(x_strt,y_strt) Inputs: unsigned *x_strt,*y_strt; Returns: unsigned fail_flag; Description: This routine gets the current start pixel address which is mapped to the upper left corner of the display. This routine returns a 'fail_flag' = 0 if the call was a success (a 1 for failure). Comments: Works in all VESA video modes. Also works in MDA, CGA, EGA and VGA Modes. Page: 7 VESA256 Graphics Library for C Programmers June 30, 1992 Version 1.1 3.3 Attribute Functions 3.3.1 vsa_set_color(color) Inputs: unsigned char color; Returns: Nothing Description: This routine sets the current drawing color which is used in drawing pixels, lines, and rectangles. The "color" is an 8 bit value from 0 to 255 which is used to index in to the Color Look Up Table (see Section 3.4). Comments: Works only in 256 color VESA video modes. 3.3.2 vsa_set_text_color(color) Inputs: unsigned char color; Returns: Nothing Description: This routine sets the current text color which is used in drawing text. The "color" is an 8 bit value from 0 to 255 which is used to index in to the Color Look Up Table (see Section 3.4). In 16 color SVGA modes, the 4 LSBs define text color. In 256 color SVGA modes, the 8 bits define text color. Comments: Works in all VESA video modes. Also works in EGA and VGA Modes. Page: 8 VESA256 Graphics Library for C Programmers June 30, 1992 Version 1.1 3.4 Color Look Up Table Functions The Color Look Up Table consists of 256 registers and each register stores an 18 bit value defining 6 bit levels for each of red, green, and blue. The drawing functions index into the Color Look Up Table with an 8 bit value (usually set with vsa_set_color) to determine the drawing color. With the following functions, the Color Look Up Table can be read or modified one register at a time or all at once in a block operation. 3.4.1 vsa_read_color_register(index,redptr,grnptr,bluptr) Inputs: unsigned index; unsigned char *redptr,*grnptr,*bluptr; Returns: Nothing Description: This routine reads the value of one of the 256 color registers as defined by 'index'. Pointers to the red, green, and blue components of the color are returned (6 bits each for red, green, and blue). Comments: Works in all VESA video modes. Also works in EGA and VGA Modes. 3.4.2 vsa_write_color_register(index,red,green,blue) Inputs: unsigned index; unsigned char red,green,blue; Returns: Nothing Description: This routine writes the value of one of the 256 color registers as defined by 'index'. The calling routine provides 'red', 'green', and 'blue' components of the color (6 bits each for red, green, and blue). Comments: Works in all VESA video modes. Also works in EGA and VGA Modes. Page: 9 VESA256 Graphics Library for C Programmers June 30, 1992 Version 1.1 3.4.3 vsa_read_color_block(start,count,array) Inputs: unsigned start,count; unsigned char far array[]; Returns: Nothing Description: This routine reads 'count' (Range: 1 to 256) consecutive color registers starting at 'start' (Range: 0 to 255) within the Color Look Up Table. The 'count' must be less than or equal to 256 - 'start'. The values read from the color registers are returned from this routine in 'array[]'. Each element of 'array[]' is a byte, and the size of 'array[]' is equal to three times 'count'. Every three bytes in 'array[]' represents the red, green, and blue color values respectively for one color register. Each color component (red,green, or blue) is a byte value but only ranges from 0 to 63. Comments: Works in all VESA video modes. Also works in EGA and VGA Modes. 3.4.4 vsa_write_color_block(start,count,array) Inputs: unsigned start,count; unsigned char array[]; Returns: Nothing Description: This routine writes 'count' (Range: 1 to 256) consecutive color registers starting at 'start' (Range: 0 to 255) within the Color Look Up Table. The 'count' must be less than or equal to 256 - 'start'. The values loaded into the color registers are passed to this routine in 'array[]'. Each element of 'array[]' is a byte, and the size of 'array[]' is equal to three times 'count'. Every three bytes in 'array[]' represents the red, green, and blue color values respectively for one color register. Each color component (red,green, or blue) is a byte value but only ranges from 0 to 63. Comments: Works in all VESA video modes. Also works in EGA and VGA Modes. Page: 10 VESA256 Graphics Library for C Programmers June 30, 1992 Version 1.1 3.5 Text Functions 3.5.1 vsa_set_text_cursor(row,col) Inputs: unsigned row, col; Returns: Nothing Description: This routine sets the current text cursor position to 'row, col' in character coordinates (not pixel coordinates). The current text cursor position is only used by vsa_write_string_alt. Comments: Works in all VESA video modes. Also works in EGA and VGA Modes. 3.5.2 vsa_set_text_cursor_mode(mode) Inputs: unsigned mode; Returns: Nothing Description: This routine determines the mode of the text cursor operation. If 'mode' is '0' (the default after calling vsa_init), the text cursor is not updated after a new text string is written with vsa_write_string or vsa_write_string_alt. If 'mode' is '1', then the text cursor is moved to the end of the text string after executing vsa_write_string or vsa_write_string_alt. Comments: Works in all VESA video modes. Also works in EGA and VGA Modes. 3.5.3 vsa_write_char(row,col,alpha) Inputs: unsigned char row,col; char alpha; Returns: Nothing Description: This routine writes a the single character 'alpha' at position (row,col). The character is written with the current text color. After execution, the current text cursor position remains set to (row, col). Comments: Works in all VESA video modes. Also works in EGA and VGA Modes. Page: 11 VESA256 Graphics Library for C Programmers June 30, 1992 Version 1.1 3.5.4 vsa_write_string(row,col,string) Inputs: unsigned char row,col; char string[]; Returns: Nothing Description: This routine writes a null terminated text string 'string' at position (row,col). The text is written with the current text color. After execution, if the text cursor mode is '0', the text cursor remains at 'row,col', otherwise it is set to the end of the text string just written. Comments: Works in all VESA video modes. Also works in EGA and VGA Modes. 3.5.5 vsa_write_string_alt(string) Inputs: char string[]; Returns: Nothing Description: This routine writes a null terminated text string 'string' at the current text cursor position as determined by vsa_set_text_cursor. The text is written with the current text color. After execution, if the text cursor mode is '0', the current text cursor remains unchanged, otherwise it is set to the end of the text string just written. Comments: Works in all VESA video modes. Also works in EGA and VGA Modes. 3.6 Basic Drawing Functions 3.6.1 vsa_move_to(x,y) Inputs: unsigned x,y; Returns: Nothing Description: This routine sets the current cursor position to 'x,y'. The current cursor position is used by the vsa_line_to, vsa_rect_fill, and vsa_rect functions. Comments: none Page: 12 VESA256 Graphics Library for C Programmers June 30, 1992 Version 1.1 3.6.2 vsa_set_pixel(x,y) Inputs: unsigned x,y; Returns: Nothing Description: This routine draws a single pixel at 'x,y' with the current drawing color. Comments: Works in all VESA 256 color video modes. 3.6.3 vsa_line_to(x,y) Inputs: int x,y; Returns: Nothing Description: This routine draws a line from the current cursor position to 'x,y' with the current drawing color. Then the current cursor position is moved to 'x,y'. Comments: Works in all VESA 256 color video modes. 3.6.4 vsa_rect_fill(x,y) Inputs: int x,y; Returns: Nothing Description: This routine draws a filled rectangle from the current cursor position to the rectangles diagonal position 'x,y' with the current color. Comments: Works in all VESA 256 color video modes. 3.6.5 vsa_rect(x,y) Inputs: int x,y; Returns: Nothing Description: This routine draws a rectangle from the current cursor position to the rectangles diagonal position 'x,y' with the current color. Comments: Works in all VESA 256 color video modes. Page: 13 VESA256 Graphics Library for C Programmers June 30, 1992 Version 1.1 3.6.6 vsa_h_line(y,x0,x1) Inputs: int y,x0,x1; Returns: Nothing Description: This routine draws a horizontal line from 'x0,y' to 'x1,y'. The line is drawn with the current drawing color. For horizontal lines this function is quicker than the vsa_line_to function. Comments: Works in all VESA 256 color video modes. 3.6.7 vsa_v_line(x,y0,y1) Inputs: int x,y0,y1; Returns: Nothing Description: This routine draws a vertical line from 'x,y0' to 'x,y1'. The line is drawn with the current drawing color. For vertical lines this function is quicker than the vsa_line_to function. Comments: Works in all VESA 256 color video modes. 3.7 Specialized Drawing Functions 3.7.1 vsa_raster_line(x0,x1,y,array) Inputs: unsigned x0,x1,y; unsigned char array[]; Returns: Nothing Description: This routine draws a horizontal raster line from 'x0,y' to 'x1,y'. The 'array[]' values specify each pixel's color value. If x0 <= x1, then 'array[0]' defines the color of the first pixel in the line at 'x0,y'. If x1 < x0, then 'array[0]' defines the color of the first pixel in the line at 'x1,y'. Comments: Works in all VESA 256 color video modes. Page: 14 VESA256 Graphics Library for C Programmers June 30, 1992 Version 1.1 4.0 Nitty Gritties 4.1 Registration Information If you find the VSA256 Graphics Library useful, a registration of $20 would be appreciated. If you register, you will receive a diskette and manual for the next upgrade of the software (see Section 5.0 Coming Attractions). Please state the version number of the software you are presently using. Send check or money order to: Spyro Gumas 1668 Shady Brook Drive Fullerton, Ca. 92631 4.2 Software License VSA256 Graphics Library, Version 1.0 Copyright Spyro Gumas, 1992. All Rights Reserved. You are free to copy and distribute the VSA256 Graphics Library if: 1) It is used strictly for non-commercial purposes. 2) No fee is charged for use, copying or distribution. 3) It is not modified in any way. Clubs and user groups may charge a nominal fee not to exceed ($10) for expenses and handling while distributing the VSA256 Graphics Library. Site licenses and commercial licenses for the VSA256 Graphics Library are available. Consult the file ORDER.TXT for more information, or contact me for more information. 4.3 Disclaimer This software is provided "as is". All warranties relating to this software are disclaimed, whether expressed or implied, including without limitation any implied warranties of merchantability or fitness for a particular purpose. Neither the author nor an agent of the author will be liable for any special, incidental, consequential, indirect or similar damages due to loss of data or any other reason, even if the author or an agent of the author has been advised of the possibility of such damages. In no event shall the author's or an agent of the author's liability for any damages ever exceed the price paid for the license to use software, regardless of the form of the claim. The person using the software bears all risk as to the quality and performance of the software. Page: 15 VESA256 Graphics Library for C Programmers June 30, 1992 Version 1.1 4.4 Technical Support If you have any questions or comments about the VSA256 Graphics Library, please write me at: Spyro Gumas 1668 Shady Brook Drive Fullerton, Ca. 92631 Page: 16 VESA256 Graphics Library for C Programmers June 30, 1992 Version 1.1 5.0 Coming Attractions Version 2.0 of the VSA256 Graphics Library incorporates new functions and drawing speed improvements while preserving compatibility with the previous version. With the $20 registration fee, you will automatically receive this upgrade. Some of the Version 2.0 new functions are: - vsa_triangle_fill: General purpose triangle fill for n-gon drawing, finite element models, etc. - vsa_triangle_shade: 3D triangle fill using Gouraud shading for light modelling effects. - vsa_antialias_line: Smooth line generation which eliminates "the jaggies". - vsa_circle: Circle drawing. - vsa_arc: General arc sections. 5.1 Graphics Library Extensions The VSA256 Graphics Library (Version 1.1 and higher) is a base library which is supported by library extensions for more specialized tasks. New extensions will be developed periodically. The current extensions are: TIFF256 Graphics Library Extension 1.0 - This library extension provides functions which operate with Tagged Image File Format (TIFF) images. With these functions, you can traverse the image file, extract image information, and display the images as part of your own program. The image types supported include Bilevel, Grayscale, Palette Color and RGB True Color. This is shareware software available from the same place that you got the VSA256 Graphics Library. TIFF256 Graphics Library Extension 2.0 - This is the registered version of the TIFF256 Graphics Library Extension. In addition to the capabilities provided by the version 1.0, version 2.0 lets you modify the TIFF images and write them back to TIFF files. Furthermore, any image that you generate with VSA256 can be saved as a TIFF file. You can get your legal fingers on this with a $20 registration fee, or get both VSA256 Ver. 2.0 and TIFF256 Ver 2.0 for the highly discounted price of $30. See the ORDER.TXT for ordering information. Page: 17 VESA256 Graphics Library for C Programmers June 30, 1992 Version 1.1 6.0 Appendix 6.1 VSA.H Include File /*.................................. VSA.H ................. 5-8-92 ........*/ /* This file declares the VSA256 Graphics Library functions and global */ /* parameters used throughout the graphics routines. */ /* */ /* Copyright Spyro Gumas, 1992. All Rights Reserved. */ /*..........................................................................*/ /*..........................................................................*/ /* Function Prototypes */ /*..........................................................................*/ unsigned _far _cdecl vsa_set_svga_mode( unsigned ); unsigned _far _cdecl vsa_get_svga_mode( unsigned _far * ); unsigned _far _cdecl vsa_set_display_start( unsigned, unsigned ); unsigned _far _cdecl vsa_get_display_start( unsigned _far *, unsigned _far * ); unsigned _far _cdecl vsa_init( unsigned ); void _far _cdecl vsa_set_color( unsigned ); void _far _cdecl vsa_set_text_color( unsigned ); void _far _cdecl vsa_set_text_cursor_mode( unsigned ); void _far _cdecl vsa_set_text_cursor( unsigned, unsigned ); void _far _cdecl vsa_write_char( unsigned, unsigned, char ); void _far _cdecl vsa_write_string( unsigned, unsigned, unsigned, char _far * ); void _far _cdecl vsa_write_string_alt( char _far * ); void _far _cdecl vsa_read_color_register( unsigned, unsigned char _far *, unsigned char _far *, unsigned char _far *); void _far _cdecl vsa_write_color_register( unsigned, unsigned char, unsigned char, unsigned char ); void _far _cdecl vsa_read_color_block( unsigned, unsigned, unsigned char _far * ); void _far _cdecl vsa_write_color_block( unsigned, unsigned, unsigned char _far * ); void _far _cdecl vsa_move_to( unsigned, unsigned ); void _far _cdecl vsa_set_pixel( unsigned, unsigned ); void _far _cdecl vsa_line_to( unsigned, unsigned ); void _far _cdecl vsa_rect_fill( unsigned, unsigned ); void _far _cdecl vsa_rect( unsigned, unsigned ); void _far _cdecl vsa_h_line( unsigned, unsigned, unsigned ); void _far _cdecl vsa_v_line( unsigned, unsigned, unsigned ); void _far _cdecl vsa_raster_line( unsigned, unsigned,unsigned, unsigned char _far *); void _far _cdecl vsa_about( void ); Page: 18 VESA256 Graphics Library for C Programmers June 30, 1992 Version 1.1 /*..........................................................................*/ /* Function Prototypes */ /* The following functions only work in VESA mode 105h (1024 x 768 x 8) */ /* and should run a little faster, but they should only be used */ /* experimentally cause they "aint really checked out". */ /*..........................................................................*/ void _far _cdecl vsa_line_to_x( unsigned, unsigned ); void _far _cdecl vsa_rect_fill_x( unsigned, unsigned ); void _far _cdecl vsa_h_line_x( unsigned, unsigned, unsigned ); void _far _cdecl vsa_v_line_x( unsigned, unsigned, unsigned ); void _far _cdecl vsa_raster_line_x( unsigned, unsigned,unsigned, unsigned char _far *); /*..........................................................................*/ /* External Parameter Declarations */ /*..........................................................................*/ unsigned XResolution, YResolution, XCharResolution, YCharResolution; unsigned char XCharSize, YCharSize; unsigned char BitsPerPixel; Page: 19