VSA256 Graphics Library For C Programmers Version 1.0 Mar. 27, 1992 Copyright Spyro Gumas, 1992. All Rights Reserved. VSA256 Graphics Library for C Programmers March 27, 1992 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 7 3.3.1 vsa_set_color 7 3.3.2 vsa_set_text_color 7 3.4 Color Look Up Table Functions 8 3.4.1 vsa_read_color_register 8 3.4.2 vsa_write_color_register 8 3.4.3 vsa_read_color_block 9 3.4.4 vsa_write_color_block 9 3.5 Text Functions 9 3.5.1 vsa_write_char 9 3.5.2 vsa_write_string 10 3.6 Basic Drawing Functions 10 3.6.1 vsa_move_to 10 3.6.2 vsa_set_pixel 10 3.6.3 vsa_line_to 10 3.6.4 vsa_rect_fill 11 3.6.5 vsa_rect 11 3.6.6 vsa_h_line 11 3.6.7 vsa_v_line 11 3.7 Specialized Drawing Functions 12 3.7.1 vsa_raster_line 12 4.0 Nitty Gritties 13 4.1 Registration Information 13 4.2 Software License 13 4.3 Disclaimer 13 5.0 Coming Attractions 15 6.0 Appendix 16 6.1 VSA.H Include File 16 Page: 2 VSA256 Graphics Library for C Programmers March 27, 1992 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). The distribution of the VSA256 Graphics Library consists of the 11 files listed below plus the drivers listed in Section 2.1. These files are archived in the self extracting file VSALIB10.EXE. To extract, just type VSALIB10 in the directory that you want the files extracted to. When distributing the VSA256 Graphics Library, distribute VSALIB10.EXE instead of the individual files. VSA_DEMO.C Demonstration program (Source Code). VSA_DEMO.EXE Demonstration program (Executable). VSA256T.LIB VSA256 Graphics Library (Tiny Memory Model). VSA256S.LIB VSA256 Graphics Library (Small Memory Model). VSA256C.LIB VSA256 Graphics Library (Compact Memory Model). VSA256M.LIB VSA256 Graphics Library (Medium Memory Model). VSA256L.LIB VSA256 Graphics Library (Large Memory Model). VSA256H.LIB VSA256 Graphics Library (Huge Memory Model). 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 VSA256 Graphics Library for C Programmers March 27, 1992 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(mode) 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 VSA256 Graphics Library for C Programmers March 27, 1992 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 memory model being used. Tiny - VSA256T.LIB Small - VSA256S.LIB Compact - VSA256C.LIB Medium - VSA256M.LIB Large - VSA256L.LIB Huge - VSA256H.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 various 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 VSA256 Graphics Library for C Programmers March 27, 1992 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 routine through the 'video_mode' parameter. This routine returns a 'fail_flag' = 0 if the call was a success (a 1 for failure). Page: 6 VSA256 Graphics Library for C Programmers March 27, 1992 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. 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 Page: 7 VSA256 Graphics Library for C Programmers March 27, 1992 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. 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: 8 VSA256 Graphics Library for C Programmers March 27, 1992 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. 3.5 Text Functions 3.5.1 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. Page: 9 VSA256 Graphics Library for C Programmers March 27, 1992 Comments: Works in all VESA video modes. Also works in EGA and VGA Modes. 3.5.2 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. 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 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 Page: 10 VSA256 Graphics Library for C Programmers March 27, 1992 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. 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. Page: 11 VSA256 Graphics Library for C Programmers March 27, 1992 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: 12 VSA256 Graphics Library for C Programmers March 27, 1992 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: 13 VSA256 Graphics Library for C Programmers March 27, 1992 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: 14 VSA256 Graphics Library for C Programmers March 27, 1992 5.0 Coming Attractions Version 2.0 of the VSA256 Graphics Library is in the works, and it will incorporate 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. - General image processing functions (display image, smooth, sharpen, custom filter). - Window functions. Page: 15 VSA256 Graphics Library for C Programmers March 27, 1992 6.0 Appendix 6.1 VSA.H Include File /*................................. VSA.H ................ 3-27-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 vsa_set_svga_mode( unsigned ); unsigned vsa_get_svga_mode( unsigned * ); unsigned vsa_set_display_start( unsigned, unsigned ); unsigned vsa_get_display_start( unsigned *, unsigned * ); unsigned vsa_init( unsigned ); void vsa_set_color( unsigned ); void vsa_set_text_color( unsigned ); void vsa_write_char( unsigned, unsigned, char ); void vsa_write_string( unsigned, unsigned, char * ); void vsa_read_color_register( unsigned, unsigned char *, unsigned char *, unsigned char *); void vsa_write_color_register( unsigned, unsigned char, unsigned char, unsigned char ); void vsa_read_color_block( unsigned, unsigned,unsigned char _far * ); void vsa_write_color_block( unsigned, unsigned,unsigned char * ); void vsa_move_to( unsigned, unsigned ); void vsa_set_pixel( unsigned, unsigned ); void vsa_line_to( unsigned, unsigned ); void vsa_rect_fill( unsigned, unsigned ); void vsa_rect( unsigned, unsigned ); void vsa_h_line( unsigned, unsigned, unsigned ); void vsa_v_line( unsigned, unsigned, unsigned ); void vsa_raster_line( unsigned, unsigned,unsigned, unsigned char *); /*..........................................................................*/ /* Function Prototypes */ /* The following functions only work in VESA mode 105h (1024 x 768 x 8) */ /* and should run alittle faster, but they should only be used */ /* experimentally cause they "ain't really checked out". */ /*..........................................................................*/ void vsa_line_to_x( unsigned, unsigned ); void vsa_rect_fill_x( unsigned, unsigned ); void vsa_h_line_x( unsigned, unsigned, unsigned ); void vsa_v_line_x( unsigned, unsigned, unsigned ); void vsa_raster_line_x( unsigned, unsigned,unsigned, unsigned char *); /*..........................................................................*/ /* External Parameter Declarations */ /*..........................................................................*/ unsigned XResolution, YResolution, XCharResolution, YCharResolution; unsigned char XCharSize, YCharSize; unsigned char BitsPerPixel; Page: 16