VFOSSIL - An OS/2-Subset Video FOSSIL Appendage Version 1.00, May 23, 1988 Rick Moore, Solar Wind Computing FidoNet Address: 1:115/333 FidoNet Standards Committee index: FSC-0021 Copyright (C) 1988, Rick Moore, Homewood, IL, 60430. All rights reserved. This document may be distributed freely as long as it is distributed in its original, unmodified form. VFOSSIL - An OS/2-Subset Video FOSSIL Appendage FSC-0021 Page 2 VFOSSIL design criteria: The VFOSSIL appendage proposed here is designed to be an compatible subset of the OS/2 VIO subsystem. All services are proper subsets of the equivalent OS/2 VIO API's, and if you stick to the services defined in this document, you will be able to compile and run your programs with very minor changes in an OS/2 environment. VFOSSIL (and OS/2 VIO at this time) only supports text modes. It is possible to use the "set mode" service to set a graphics mode, but that is the only support for pixel-oriented graphics functions provided by VFOSSIL. The minimum environment supported by VFOSSIL is a 80 by 24 monochrome text screen, and any program using VFOSSIL calls should be capable of operating within this level of support. By querying the VFOSSIL, the full capabilities of a specific implementation may be determined and used, but all programs using VFOSSIL should be capable of operating with the 80 by 24 monochrome text environment. The organization of the video screen: The virtual screen is organized in rows of columns of character/attribute pairs, hereafter referred to as cells. The characters actually displayed are located on the even addresses, the attribute for each character is located at character+1. Regardless of the manner in which the video screen is actually organized, the programmer will view it as a a contiguous area of memory, referred to as the "logical video buffer" (LVB). The LVB is (NumRow * NumCol) cells in length. VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021 Page 3 VFOSSIL installation: The VFOSSIL appendage is installed via the standard FOSSIL external application function. The FOSSIL interrupt (14h) is issued with the following parameters: AH = 7Eh Install appendage AL = 81h VFOSSIL application code DX = offset of VFOSSIL entry point ES = segment of VFOSSIL entry point Upon return from the FOSSIL interrupt, the following registers are modified: AX = 1954h FOSSIL signature BL = 81h VFOSSIL application code BH = 01h - Installation was successful 00h - Installation was unsuccessful VFOSSIL removal: The VFOSSIL appendage is removed via the standard FOSSIL external application function. The FOSSIL interrupt (14h) is issued with the following parameters: AH = 7Fh Remove appendage AL = 81h VFOSSIL application code DX = offset of VFOSSIL entry point ES = segment of VFOSSIL entry point Upon return from the FOSSIL interrupt, the following registers are modified: AX = 1954h FOSSIL signature BL = 81h VFOSSIL identification code BH = 01h - Removal was successful 00h - Removal was unsuccessful VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021 Page 4 VFOSSIL functions called via the standard FOSSIL interrupt (14h): The following three functions are called via the standard FOSSIL interrupt, int 14h. All other VFOSSIL functions are called via the OS/2 compatible direct call interface. Subfunction 00h - Return VFOSSIL information Entry: AH = 81h VFOSSIL application code AL = 00h VFOSSIL subfunction ES:DI = Far pointer to VFOSSIL information structure Exit: AX = 1954h FOSSIL signature This function is used before calling the open function (sub-function 01h) to determine the characteristics of the VFOSSIL. Such things returned in the structure are current version level and number of functions supported. The format of the information structure filled in by this call is as follows: DW Size of this structure, in bytes, including this field DW VFOSSIL major version DW VFOSSIL revision level DW Highest VFOSSIL application function supported Subfunction 01h - Open VFOSSIL Entry: AH = 81h VFOSSIL application code AL = 01h VFOSSIL subfunction CX = Length of application function table (in bytes) ES:DI = Far pointer to application function table Exit: BH = Highest VFOSSIL application function supported AX = 1954h FOSSIL signature This VFOSSIL subfunction will initialize the table pointed to by ES:DI with far pointers to the VFOSSIL application services. The number of far pointers initialized is equal to the value returned in register BH + 1. Under no circumstances will the number of far pointers initialized exceed the value passed in register CX / 4. All other processing necessary to ready the VFOSSIL for use by the application program should be performed at this time. Subfunction 02h - Close VFOSSIL Entry: AH = 81h VFOSSIL application code AL = 02h VFOSSIL subfunction Exit: AX = 1954h FOSSIL signature This VFOSSIL function terminates all VFOSSIL operations, and leaves the VFOSSIL in a state that allows for it to be removed from memory, or to be reinitialized via VFOSSIL function 01h. VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021 Application Services Page 5 VFOSSIL application services: All calls to VFOSSIL services are made in a manner identical to the OS/2 API protocol. All services are entered via a far call, with parameters passed via the stack. All services return an error code in register AX. The parameters are pushed onto the stack Pascal-style, from left to right. The parameters are passed on the stack in one of the three following ways: WORD A one-word value pushed directly onto the stack DWRD A double-word value pushed directly onto the stack (low word first, followed by the high word) PTR A far pointer to a memory area. Far pointers are passed as double-word values, segment followed by offset. Single-word and double-word input parameters are always passed as WORD and DWRD. If the service returns information in the parameter field itself, then it is pushed as a PTR, even if the object is a WORD or a DWRD. Variable length parameters, such as data structures or ASCIIZ strings, are always passed as PTR objects. All cursor coordinates are expressed as zero (0) based numbers. Each VFOSSIL service requires a "handle" parameter as the last parameter passed to the service. At this time, zero (0) is the only valid handle. The actual addresses used to call the application services are contained in the address table filled in by the VFOSSIL initialization call described above. All addresses are in far (segment/offset) format. Here is the format of the application service address table: Table +00h VioGetMode Query current video mode +04h VioSetMode Set video mode +08h VioGetConfig Query video hardware configuration +0Ch VioWrtTTY Write data in TTY mode +10h VioGetANSI Query current ANSI state +14h VioSetANSI Set ANSI state +18h VioGetCurPos Query current cursor position +1Ch VioSetCurPos Set cursor position +20h VioGetCurType Query current cursor parameters +24h VioSetCurType Set cursor parameters +28h VioScrollUp Scroll screen up +2Ch VioScrollDn Scroll screen down +30h VioReadCellStr Read cell string from display +34h VioReadCharStr Read char string from display +38h VioWrtCellStr Write cell string +3Ch VioWrtCharStr Write char string (existing attributes) +40h VioWrtCharStrAtt Write char string (constant attributes) +44h VioWrtNAttr Replicate attribute +48h VioWrtNCell Replicate cell +4Ch VioWrtNChar Replicate char VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021 Application Services Page 6 VioGetMode - Query current video mode Parameters: PTR Pointer to a video mode data structure WORD VIO handle (must be 0) Video mode data structure: DW Structure length (including this field) DB Mode characteristics -------0 Monochrome/printer adapter -------1 Other adapter ------0- Text mode ------1- Graphics mode -----0-- Enable color -----1-- Disable color (black and white) DB Number of colors supported by the display 1 = 2 colors 2 = 4 colors 4 = 16 colors DW Number of text columns DW Number of text rows DW Reserved DW Reserved DD Reserved A partial video mode buffer may be specified. VFOSSIL returns only the data that will fit into the buffer. The minimum buffer length is 3, and the maximum buffer length is 12. Partial fields are not returned. Error codes returned: 0 - Successful completion 116 - Internal VIO failure 382 - Buffer too small 436 - Invalid VIO handle VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021 Application Services Page 7 VioSetMode - Set video mode Parameters: PTR Pointer to a video mode data structure (see VioGetMode) WORD VIO handle (must be 0) A partial video mode buffer may be specified. The minimum buffer length is 3, and the maximum buffer length is 12. Partial fields are not supported. The remaining fields are set to default values. Error codes returned: 0 - Successful completion 116 - Internal VIO failure 355 - Unsupported mode 382 - Buffer too small 421 - Invalid VIO parameter 436 - Invalid VIO handle VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021 Application Services Page 8 VioGetConfig - Query video hardware configuration Parameters: PTR Pointer to a video configuration data area WORD VIO handle (must be 0) Video configuration data area: DW Structure length (includes this field) DW Adapter type 0 = Monochrome/printer 1 = CGA 2 = EGA 3 = VGA 7 = 8514A DW Display type 0 = Monochrome 1 = Color 2 = Enhanced color 9 = 8514 DD Adapter memory size Error codes returned: 0 - Successful completion 116 - Internal VIO failure 382 - Buffer too small 436 - Invalid VIO handle VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021 Application Services Page 9 VioWriteTTY - Write data in TTY mode Parameters: WORD Pointer to a character string that VFOSSIL will write to the screen WORD String length WORD VIO handle (must be 0) This service writes a string to the video screen in TTY mode. The characters CR, LF, BS, TAB, and BELL are interpreted as control values rather than being display as values. If ANSI mode has been enabled (see VioGetANSI, VioSetANSI), then ANSI control sequences are also interpreted as control strings. In ANSI mode, this service is not required to be reentrant, and should not be called when a MS/DOS function is in progress. When in non-ANSI mode, this service is required to be reentrant, and may be called from within a MS/DOS function. If the write goes beyond the end of a line, it continues at the start of the next line. The write terminates at the end of the screen. The cursor is left positioned at the next character position to be written. Error codes returned: 0 - Successful completion 116 - Internal VIO failure 436 - Invalid VIO handle VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021 Application Services Page 10 VioGetANSI - Query current ANSI state Parameters: PTR Pointer to a one-word field in which VFOSSIL will return the current ANSI state: 0 = Off 1 = On WORD VIO handle (must be 0) Error codes returned: 0 - Successful completion 116 - Internal VIO failure 436 - Invalid VIO handle VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021 Application Services Page 11 VioSetANSI - Set ANSI state Parameters: PTR Pointer to a one-word field indicating how ANSI processing is to be set: 0 = Off 1 = On WORD VIO handle (must be 0) Error codes returned: 0 - Successful completion 116 - Internal VIO failure 421 - Invalid VIO parameter 436 - Invalid VIO handle VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021 Application Services Page 12 VioGetCurPos - Query current cursor position Parameters: PTR Pointer to a one word field in which VFOSSIL will return the current cursor row PTR Pointer to a one word field in which VFOSSIL will return the current cursor column WORD VIO handle (must be 0) This service returns the current cursor position. Cursor coordinates are zero based. Error codes returned: 0 - Successful completion 116 - Internal VIO failure 436 - Invalid VIO handle VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021 Application Services Page 13 VioSetCurPos - Set cursor position Parameters: WORD Desired cursor row WORD Desired cursor column WORD VIO handle (must be 0) This service sets the cursor position to the zero based coordinates specified by the parameters. If either of the parameters is invalid, the cursor position is left unchanged. Error codes returned: 0 - Successful completion 116 - Internal VIO failure 358 - Invalid row value 359 - Invalid column value 436 - Invalid VIO handle VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021 Application Services Page 14 VioGetCurType - Query current cursor parameters Parameters: PTR Pointer to a cursor type data area WORD VIO handle (must be 0) Cursor type data area: DW Cursor start line DW Cursor end line DW Cursor width (always 1) DW Cursor attribute (-1 = hidden) Error codes returned: 0 - Successful completion 116 - Internal VIO failure 436 - Invalid VIO handle VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021 Application Services Page 15 VioSetCurType - Set cursor parameters Parameters: PTR Pointer to a cursor type data area (see VioGetCurType) WORD VIO handle (must be 0) Error codes returned: 0 - Successful completion 116 - Internal VIO failure 421 - Invalid VIO parameter 436 - Invalid VIO handle VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021 Application Services Page 16 VioScrollUp - Scroll screen up Parameters: WORD Top row of the scroll area WORD Left column of the scroll area WORD Bottom row of the scroll area WORD Right column of the scroll area WORD Number of rows to scroll. A value of -1 causes the scroll area to be cleared. PTR Pointer to a char/attr cell that is used to fill the scroll area. WORD VIO handle (always 0) Error codes returned: 0 - Successful completion 116 - Internal VIO failure 358 - Invalid row value 359 - Invalid column value 436 - Invalid VIO handle VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021 Application Services Page 17 VioScrollDn - Scroll screen down Parameters: WORD Top row of the scroll area WORD Left column of the scroll area WORD Bottom row of the scroll area WORD Right column of the scroll area WORD Number of rows to scroll. A value of -1 causes the scroll area to be cleared. PTR A pointer to a char/attr cell that is used to fill the scroll area. WORD VIO handle (always 0) Error codes returned: 0 - Successful completion 116 - Internal VIO failure 358 - Invalid row value 359 - Invalid column value 436 - Invalid VIO handle VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021 Application Services Page 18 VioReadCellStr - Read cell string from display Parameters: PTR Pointer to a buffer into which the cell string is to be placed PTR Pointer to a one-word field which, upon entry, specifies the length of the cell buffer (in bytes), and, on return, contains the number of bytes actually read. Each cell occupies two bytes, so the number of cells read is equal to half of the buffer length specified. WORD Row where the read is to start WORD Column where the read is to start WORD VIO handle (always 0) If the read request extends beyond the end of the line, it continues at the first column of the next line. If an attempt is made to read past the end of the screen, the read operation terminates and the length field is set to the actual number of bytes read. Error codes returned: 0 - Successful completion 116 - Internal VIO failure 358 - Invalid row value 359 - Invalid column value 436 - Invalid VIO handle VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021 Application Services Page 19 VioReadCharStr - Read character string from display Parameters: PTR Pointer to a buffer into which the character string is to be placed PTR Pointer to a one-word field which, upon entry, specifies how many characters are to be read, and, on return, contains the number of characters actually read. WORD Row where the read is to start WORD Column where the read is to start WORD VIO handle (always 0) If the read request extends beyond the end of the line, it continues at the first column of the next line. If an attempt is made to read past the end of the screen, the read operation terminates and the length field is set to the actual number of characters read. Error codes returned: 0 - Successful completion 116 - Internal VIO failure 358 - Invalid row value 359 - Invalid column value 436 - Invalid VIO handle VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021 Application Services Page 20 VioWrtCellStr - Write a cell string Parameters: PTR Pointer to the cell string to be written WORD Cell string length. Since each cell occupies two bytes, this number is twice the number of cells to be written. WORD Row at which write is to begin WORD Column at which write is to begin WORD Vio handle (must be 0) If the write request extends beyond the end of the line, it continues at the first column of the next line. If an attempt is made to write past the end of the screen, the write operation terminates. Error codes returned: 0 - Successful completion 116 - Internal VIO failure 358 - Invalid row value 359 - Invalid column value 436 - Invalid VIO handle VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021 Application Services Page 21 VioWrtCharStr - Write a character string, using existing attributes Parameters: PTR Pointer to the character string to be written WORD Character string length WORD Row at which write is to begin WORD Column at which write is to begin WORD Vio handle (must be 0) The attributes of the display cells whose characters are replaced are not modified. If the write request extends beyond the end of the line, it continues at the first column of the next line. If an attempt is made to write past the end of the screen, the write operation terminates. Error codes returned: 0 - Successful completion 116 - Internal VIO failure 358 - Invalid row value 359 - Invalid column value 436 - Invalid VIO handle VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021 Application Services Page 22 VioWrtCharStrAtt - Write a character string, using constant attribute Parameters: PTR Pointer to the character string to be written WORD Character string length WORD Row at which write is to begin WORD Column at which write is to begin PTR Pointer to the display attribute to be used with each character written WORD Vio handle (must be 0) If the write request extends beyond the end of the line, it continues at the first column of the next line. If an attempt is made to write past the end of the screen, the write operation terminates. Error codes returned: 0 - Successful completion 116 - Internal VIO failure 358 - Invalid row value 359 - Invalid column value 436 - Invalid VIO handle VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021 Application Services Page 23 VioWrtNAttr - Replicate an attribute byte, leaving characters unchanged Parameters: PTR Pointer to the display attribute to be replicated WORD Replication count WORD Row at which write is to begin WORD Column at which write is to begin WORD Vio handle (must be 0) The characters contained in the display cells whose attributes are replaced are not modified. If the write request extends beyond the end of the line, it continues at the first column of the next line. If an attempt is made to write past the end of the screen, the write operation terminates. Error codes returned: 0 - Successful completion 116 - Internal VIO failure 358 - Invalid row value 359 - Invalid column value 436 - Invalid VIO handle VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021 Application Services Page 24 VioWrtNCell - Replicate a cell Parameters: PTR Pointer to the cell to be replicated WORD Replication count WORD Row at which write is to begin WORD Column at which write is to begin WORD Vio handle (must be 0) If the write request extends beyond the end of the line, it continues at the first column of the next line. If an attempt is made to write past the end of the screen, the write operation terminates. Error codes returned: 0 - Successful completion 116 - Internal VIO failure 358 - Invalid row value 359 - Invalid column value 436 - Invalid VIO handle VFOSSIL - An OS/2 Subset Video FOSSIL Appendage FSC-0021 Application Services Page 25 VioWrtNChar - Replicate an character, leaving attributes unchanged Parameters: PTR Pointer to the character to be replicated WORD Replication count WORD Row at which write is to begin WORD Column at which write is to begin WORD Vio handle (must be 0) The attributes contained in the display cells whose characters are replaced are not modified. If the write request extends beyond the end of the line, it continues at the first column of the next line. If an attempt is made to write past the end of the screen, the write operation terminates. Error codes returned: 0 - Successful completion 116 - Internal VIO failure 358 - Invalid row value 359 - Invalid column value 436 - Invalid VIO handle