Collection of Hack-Phreak Scene Programs

home *** CD-ROM | disk | FTP | other *** search

/ Collection of Hack-Phreak Scene Programs / cleanhpvac.zip / cleanhpvac / FGL402B.ZIP / MANUALS.ARJ / USER08.DOC < prev next >

Wrap

Text File | 1995-02-06 | 90KB | 2,009 lines

Chapter 8 Video Pages and Virtual Buffers 148 Fastgraph User's Guide Overview The amount of memory required to store one full screen of information is called a video page (or sometimes simply a page). Fastgraph offers a variety of page types, including physical pages, virtual pages, extended pages, and logical pages. In addition, virtual buffers let you define arbitrary blocks of conventional memory and treat them as if they were video memory. This chapter will discuss video pages and virtual buffers in detail, along with the Fastgraph routines to manage them. Physical Pages and Virtual Pages Pages that use the memory that resides on the video adapter are called physical pages or true pages. The number of physical pages available depends on the video mode and the amount of memory resident on the user's video adapter. All video modes have at least one physical page. In certain video modes, Fastgraph can allocate available random-access memory (RAM) and treat this memory as a video page. Pages that use standard RAM in this sense are called virtual pages. From a programmer's perspective, virtual pages are essentially identical to physical pages. The following table shows the number of physical pages in each video mode. It also indicates whether or not specific video modes support virtual pages. Mode Page Size Physical Virtual Number Description in Bytes Pages Pages 0 40 column color text 2,000 8 no 1 40 column color text 2,000 8 no 2 80 column color text 4,000 4 no 3 80 column color text 4,000 4 no 4 320x200x4 CGA graphics 16,000 1 yes 5 320x200x4 CGA graphics 16,000 1 yes 6 640x200x2 CGA graphics 16,000 1 yes 7 80 column monochrome text 4,000 1 yes 9 320x200x16 Tandy graphics 32,000 1 yes 11 720x348 Hercules graphics 31,320 2 yes 12 320x200 Hercules graphics 31,320 2 yes 13 320x200x16 EGA graphics 32,000 8 no 14 640x200x16 EGA graphics 64,000 4 no 15 640x350 EGA mono graphics 56,000 2 no 16 640x350x16 EGA graphics 112,000 2 no 17 640x480x2 MCGA/VGA graphics 38,400 1+ no 18 640x480x16 VGA graphics 153,600 1+ no 19 320x200x256 MCGA graphics 64,000 1 yes 20 320x200x256 XVGA graphics 64,000 4 no 21 320x400x256 XVGA graphics 128,000 2 no 22 320x240x256 XVGA graphics 76,800 3+ no 23 320x480x256 XVGA graphics 153,600 1+ no 24 640x400x256 SVGA graphics 256,000 4 no 25 640x480x256 SVGA graphics 307,200 2 no 26 800x600x256 SVGA graphics 480,000 2 no 27 1024x768x256 SVGA graphics 786,432 1+ no Chapter 8: Video Pages and Virtual Buffers 149 28 800x600x16 SVGA graphics 240,000 4 no 29 1024x768x16 SVGA graphics 393,216 2 no This table assumes the video adapter has 256K of video memory installed for EGA and VGA modes, and 1MB of video memory for SVGA modes. For adapters with less video memory, the number of physical pages is reduced proportionately. In other words, a 64K EGA has two video pages available instead of eight in mode 13. Similarly, a 512K SVGA has one page instead of two in modes 25 and 26, and wouldn't support mode 27. The next table summarizes the number of video pages available in SVGA graphics modes for video cards with 256K, 512K, 768K, and 1MB of video memory installed. Mode Number of pages with... Number Resolution 256K 512K 768K 1MB 24 640x400x256 1+ 2 3 4 25 640x480x256 0 1+ 1+ 2 26 800x600x256 0 1+ 1+ 2 27 1024x768x256 0 0 1 1+ 28 800x600x16 1+ 2 3 4 29 1024x768x16 0 1+ 1+ 2 In the preceding two tables, note that the number of physical pages in some video modes is followed by a plus symbol. In these modes, there is an additional partial video page available. For modes 17, 18, and 23, there is one full page (page 0) plus one partial page of 320 pixel rows (page 1). For mode 22, there are three full physical pages (numbered 0 to 2) plus one partial page of 80 pixel rows (page 3). For mode 27, there is one full page (page 0) plus one partial page of 256 pixel rows (page 1) on a 1MB SVGA card. You can safely use the partial pages as long as you don't reference pixel rows beyond their last available row. However, you cannot make a partial video page the visual page. In SVGA graphics modes (modes 24 to 29), video pages must begin on 256K boundaries to maintain compatibility between different SVGA chipsets. This results in unused video memory at the end of a page. For example, pages in mode 26 require 480,000 bytes of video memory. On a 1MB SVGA card, the two pages will begin at 0 and 524,288 (512K). Thus there are 44,288 (524,288 minus 480,000) unused video memory bytes at the end of each page. With 800 pixels (and hence 800 bytes) per screen row, this means each page has an extra 55 pixel rows per page. The actual page size is therefore 800x655, with the first 600 rows displayed. Similarly, the actual page size in mode 25 is 640x819, with the first 480 rows displayed. Physical pages are numbered starting at zero. For example, there are four physical video pages available in mode 3, and they are numbered 0 to 3. Virtual pages are numbered n to 63, where n is the number of physical pages in that mode. For example, there are two physical pages (numbered 0 and 1) and 62 virtual pages (numbered 2 to 63) in mode 11. Note only modes 4 through 12 and mode 19 offer virtual pages, and the amount of conventional memory in the user's system usually limits the number of virtual pages available (this is especially true in mode 19 because of the large page size). 150 Fastgraph User's Guide Pages With Special Meanings There are three video pages that have special meanings to Fastgraph. The visual page, as one might guess, is the video page visible on the user's display. The active page is the video page to which Fastgraph writes text or graphics information. The hidden page is meaningful only to a few Fastgraph routines and will be discussed specifically within the context of those routines. The fg_setmode routine sets all three of these pages to page 0, and it does not matter if these pages are physical or virtual. One of the most useful features of multiple video pages (either physical or virtual) is the ability to build a text or graphics image off screen (that is, on some video page besides the visual page). Then, once the image is ready, we can either transfer it to the visual page, or make the page on which the image resides the visual page. This feature is especially useful in animation, for it displays an image instantaneously instead of visibly updating the screen while producing the image. Some Simple Examples In this section, we'll present six variations of a simple program that uses four video pages. The program fills each video page with a rectangle and then displays text containing the video page number in the center of each page. The first two examples run in a specific text or graphics video mode and only use physical pages. The next two examples also run in a specific text or graphics video mode, but they also use virtual pages. The final two examples are more general and run in several video modes. You could of course write a program that essentially does the same thing as the examples in this section without using multiple video pages. However, to use Fastgraph's image display and animation routines effectively, you must first understand the concept of video pages. Before proceeding, we must introduce the Fastgraph routines fg_setpage and fg_setvpage. The fg_setpage routine defines the active video page, which causes Fastgraph to put subsequent text and graphics output on that page. The fg_setvpage routine defines the visual video page displayed on the screen. Both routines take a single integer argument between 0 and 63 that specifies the video page number. It does not matter if the referenced video page is a physical page or a virtual page. As mentioned earlier, fg_setmode makes page 0 the active and visual video page. Example 8-1 uses four video pages (numbered 0 to 3) in the 40-column color text mode (mode 1). The program first calls fg_testmode to check the availability of the requested video mode when used with four video pages. If it is available, the program calls fg_setmode to establish that video mode. The first for loop fills each of the four pages with different color rectangles and then displays black text containing the video page number in the center of each page. It does this by calling fg_setpage to define the active video page, fg_setcolor and fg_rect to draw the colored rectangles, and finally fg_setattr, fg_locate, and fg_text to display the text. The program must call fg_locate inside the loop because each video page has its own text cursor position. The second for loop successively makes each video page the visual page; the page remains displayed until you press a key. After Chapter 8: Video Pages and Virtual Buffers 151 displaying all four video pages, the program restores the original video mode and screen attributes before returning to DOS. Example 8-1. #include <fastgraf.h> #include <stdio.h> #include <stdlib.h> void main(void); #define PAGES 4 void main() { int color; int old_mode; int page; char string[8]; fg_initpm(); if (fg_testmode(1,PAGES) == 0) { printf("This program requires color.\n"); exit(1); } old_mode = fg_getmode(); fg_setmode(1); for (page = 0; page < PAGES; page++) { fg_setpage(page); color = page + 1; fg_setcolor(color); fg_rect(0,fg_getmaxx(),0,fg_getmaxy()); fg_setattr(0,color,0); fg_locate(12,17); sprintf(string,"page %d",page); fg_text(string,6); } for (page = 0; page < PAGES; page++) { fg_setvpage(page); fg_waitkey(); } fg_setmode(old_mode); fg_reset(); } Example 8-2 is similar to example 8-1, but it uses the 320x200 EGA graphics mode (mode 13) instead of a text mode. Note the only real difference between this program and the text mode version is the use of fg_setcolor instead of fg_setattr to make the text appear in black. Example 8-2. 152 Fastgraph User's Guide #include <fastgraf.h> #include <stdio.h> #include <stdlib.h> void main(void); #define PAGES 4 void main() { int color; int old_mode; int page; char string[8]; fg_initpm(); if (fg_testmode(13,PAGES) == 0) { printf("This program requires a "); printf("320 x 200 EGA graphics mode.\n"); exit(1); } old_mode = fg_getmode(); fg_setmode(13); for (page = 0; page < PAGES; page++) { fg_setpage(page); color = page + 1; fg_setcolor(color); fg_rect(0,fg_getmaxx(),0,fg_getmaxy()); fg_setcolor(0); fg_locate(12,17); sprintf(string,"page %d",page); fg_text(string,6); } for (page = 0; page < PAGES; page++) { fg_setvpage(page); fg_waitkey(); } fg_setmode(old_mode); fg_reset(); } Virtual video pages are created with Fastgraph's fg_allocate routine. The fg_allocate routine reserves conventional random-access memory (RAM) which Fastgraph then treats as a video page. The amount of memory required depends on the current video mode. The fg_allocate routine takes a single integer argument that specifies the page number by which the virtual page will be referenced. This value must be between 1 and 63. If you try to create a virtual page with a page number already assigned to a physical page, fg_allocate does nothing. For example, in the Hercules graphics modes (modes 11 and 12) there are two physical pages numbered 0 and 1. Virtual pages in the Hercules graphics modes must thus have page numbers Chapter 8: Video Pages and Virtual Buffers 153 between 2 and 63. If you tell fg_allocate to create a Hercules virtual page numbered 0 or 1, it does nothing because those video pages exist as physical pages. Similarly, if you use fg_allocate in a video mode that does not support virtual video pages, it simply returns without doing anything. A possible problem with fg_allocate can occur when there is not enough memory available for creating a virtual page in the current video mode. The fg_allocate routine returns as its function value a status code indicating whether or not it was successful. The possible values of the status code are: value meaning 0 virtual page created 1 specified page number is a physical page 7 virtual page created, but memory control blocks were destroyed 8 insufficient memory to create the virtual page If you use fg_testmode or fg_bestmode to check if the required number of video pages are available when using the requested video mode, you should not need to monitor the status code returned by fg_allocate. The fg_freepage routine releases the memory for a virtual page created with fg_allocate. It requires a single integer argument that identifies the virtual page number to release. This value must be between 0 and 63. If you try to release a physical video page, or release a virtual page that was never created, fg_freepage does nothing. It is a good idea to use fg_freepage to release all virtual video pages before a program returns control to DOS, or just before a program selects a new video mode. Example 8-3 is also similar to example 8-1, but it uses the monochrome text mode (mode 7). Because the monochrome text mode only has one physical video page, we must use virtual video pages for page numbers 1, 2, and 3. Note how fg_allocate and fg_freepage are used to create and release the virtual video pages in this example. Example 8-3. #include <fastgraf.h> #include <stdio.h> #include <stdlib.h> void main(void); #define PAGES 4 void main() { int old_mode; int page; char string[8]; fg_initpm(); if (fg_testmode(7,PAGES) == 0) { printf("This program requires monochrome.\n"); exit(1); } 154 Fastgraph User's Guide old_mode = fg_getmode(); fg_setmode(7); fg_cursor(0); for (page = 0; page < PAGES; page++) { fg_allocate(page); fg_setpage(page); fg_setcolor(7); fg_rect(0,fg_getmaxx(),0,fg_getmaxy()); fg_setattr(0,7,0); fg_locate(12,37); sprintf(string,"page %d",page); fg_text(string,6); } for (page = 0; page < PAGES; page++) { fg_setvpage(page); fg_waitkey(); fg_freepage(page); } fg_setmode(old_mode); fg_reset(); } Example 8-4 is similar to example 8-3, but it uses the standard Hercules graphics mode (mode 11) instead of the monochrome text mode. Because the Hercules graphics modes have two physical video pages, we must use virtual video pages for page numbers 2 and 3. Note the only real difference between this program and the text mode version is the use of fg_setcolor instead of fg_setattr to make the text appear in black. Example 8-4. #include <fastgraf.h> #include <stdio.h> #include <stdlib.h> void main(void); #define PAGES 4 void main() { int old_mode; int page; char string[8]; fg_initpm(); if (fg_testmode(11,PAGES) == 0) { printf("This program requires Hercules "); printf("monochrome graphics.\n"); exit(1); } old_mode = fg_getmode(); Chapter 8: Video Pages and Virtual Buffers 155 fg_setmode(11); for (page = 0; page < PAGES; page++) { fg_allocate(page); fg_setpage(page); fg_setcolor(7); fg_rect(0,fg_getmaxx(),0,fg_getmaxy()); fg_setcolor(0); fg_locate(12,37); sprintf(string,"page %d",page); fg_text(string,6); } for (page = 0; page < PAGES; page++) { fg_setvpage(page); fg_waitkey(); fg_freepage(page); } fg_setmode(old_mode); fg_reset(); } Example 8-5 is a generalized version of examples 8-1 and 8-3 that runs in any 80-column text video mode. To simplify the program, each video page is filled with rectangles of the same color. Note that fg_allocate and fg_freepage are used to manage the virtual video pages in case fg_bestmode selects the monochrome text mode (mode 7). If fg_bestmode selects one of the 80-column color text modes (which have four physical video pages), fg_allocate and fg_freepage will simply return without doing anything. Example 8-5. #include <fastgraf.h> #include <stdio.h> #include <stdlib.h> void main(void); #define PAGES 4 void main() { int old_mode, new_mode; int page; char string[8]; fg_initpm(); new_mode = fg_bestmode(80,25,PAGES); if (new_mode < 0) { printf("This program requires "); printf("an 80-column display.\n"); exit(1); } old_mode = fg_getmode(); 156 Fastgraph User's Guide fg_setmode(new_mode); fg_cursor(0); for (page = 0; page < PAGES; page++) { fg_allocate(page); fg_setpage(page); fg_setcolor(7); fg_rect(0,fg_getmaxx(),0,fg_getmaxy()); fg_setattr(0,7,0); fg_locate(12,37); sprintf(string,"page %d",page); fg_text(string,6); } for (page = 0; page < PAGES; page++) { fg_setvpage(page); fg_waitkey(); fg_freepage(page); } fg_setmode(old_mode); fg_reset(); } Example 8-6 is a generalized version of examples 8-2 and 8-4 that runs in any 320x200 graphics video mode. To simplify the program, each video page is filled with rectangles of the same color. As in example 8-5, fg_allocate and fg_freepage are used to manage the virtual video pages in case fg_bestmode selects a video mode with fewer than four physical video pages. Note the only real difference between this program and the text mode version is the use of fg_setcolor instead of fg_setattr to make the text appear in black. Example 8-6. #include <fastgraf.h> #include <stdio.h> #include <stdlib.h> void main(void); #define PAGES 4 void main() { int old_mode, new_mode; int page; char string[8]; fg_initpm(); new_mode = fg_bestmode(320,200,PAGES); if (new_mode < 0) { printf("This program requires a "); printf("320 x 200 graphics mode.\n"); exit(1); } Chapter 8: Video Pages and Virtual Buffers 157 old_mode = fg_getmode(); fg_setmode(new_mode); for (page = 0; page < PAGES; page++) { fg_allocate(page); fg_setpage(page); fg_setcolor(15); fg_rect(0,fg_getmaxx(),0,fg_getmaxy()); fg_setcolor(0); fg_locate(12,17); sprintf(string,"page %d",page); fg_text(string,6); } for (page = 0; page < PAGES; page++) { fg_setvpage(page); fg_waitkey(); fg_freepage(page); } fg_setmode(old_mode); fg_reset(); } Text Cursors As mentioned in the previous chapter, Fastgraph draws hardware characters at the position defined by the text cursor. Like the graphics cursor, the text cursor is not a cursor in the true sense, but is simply a pair of character space (row,column) coordinates with a special meaning. The first 8 video pages (that is, pages 0 through 7) each have their own text cursor. Each subsequent group of 8 video pages (pages 8 through 15, pages 16 to 23, and so forth) respectively share the same text cursor positions as the first 8 pages. This means fg_locate will update one of 8 different text cursors depending on the active video page. Similarly, fg_where returns the text cursor position for the active page. The fg_setmode routine sets all 8 text cursor positions to the character space coordinates (0,0). Example 8-7 demonstrates the use of different text cursors in an 80- column color text mode (mode 3). The program first displays the text "Page " on video page 0 (the visible page) and waits for a keystroke. It then makes page 1 the active video page, changes the text cursor location for that page, and displays the text "Page 1" on video page 1. Next, it appends the character "0" to the text originally displayed on page 0. Note that we don't need to restore the text cursor position for page 0 because it is unaffected by changing the text cursor for page 1. After waiting for another keystroke, the program makes video page 1 the visual page and then waits for yet another keystroke before returning to DOS. Example 8-7. #include <fastgraf.h> void main(void); 158 Fastgraph User's Guide void main() { int old_mode; fg_initpm(); old_mode = fg_getmode(); fg_setmode(3); fg_cursor(0); fg_setattr(10,0,0); fg_locate(1,0); fg_text("Page ",5); fg_waitkey(); fg_setpage(1); fg_locate(23,0); fg_text("Page 1",6); fg_setpage(0); fg_text("0",1); fg_waitkey(); fg_setvpage(1); fg_waitkey(); fg_setmode(old_mode); fg_reset(); } Obtaining Video Page Information Fastgraph includes two routines, fg_getpage and fg_getvpage, that respectively return the active or visual video page number. Each routine returns the video page number as its function value, and neither routine requires any arguments. When creating virtual or logical pages, you must choose a page number that does not reference a physical page or a previously created virtual or logical page. While it's of course possible to keep track of which page numbers will be available in a given video mode, Fastgraph's fg_findpage function can make the job easier. It returns an unused page number, which you can then pass to any of Fastgraph's virtual or logical page allocation routines. If there are no more available (that is, all 64 entries in the internal page tables are in use), fg_findpage returns zero. The fg_getaddr routine is sometimes useful when using virtual pages. It returns as its function value the segment address (in real mode) or segment selector (in protected mode) for the start of the active video page. It does not require any arguments. Although fg_getaddr is more useful when using virtual video pages, it works equally well with physical video pages. Example 8-9 illustrates the use of fg_getpage, fg_getvpage, fg_findpage, and fg_getaddr in the standard VGA/MCGA 256-color graphics mode (mode 19). This video mode offers only one physical page, so the program uses fg_findpage Chapter 8: Video Pages and Virtual Buffers 159 to find an unused page number (which will be page 1 in mode 19), and then calls fg_allocate to create a virtual video page. After creating the virtual page, the program makes it the active video page; page 0 remains the visual video page. The fg_getpage routine then returns the active page number, followed by a call to fg_getvpage to return the visual page number (0). Next, the program uses fg_getaddr to return the segment address/selector for the two video pages. Finally, it restores the original video mode and screen attributes, displays the returned values, and returns to DOS. Example 8-9. #include <fastgraf.h> #include <stdio.h> void main(void); void main() { int old_mode; int active, visual; int page, page0, page1; fg_initpm(); old_mode = fg_getmode(); fg_setmode(19); page = fg_findpage(); fg_allocate(page); fg_setpage(page); active = fg_getpage(); visual = fg_getvpage(); fg_setpage(0); page0 = fg_getaddr(); fg_setpage(page); page1 = fg_getaddr(); fg_freepage(page); fg_setmode(old_mode); fg_reset(); printf("Active page is %d.\n",active); printf("Visual page is %d.\n",visual); printf("Page 0 address is %4X\n",page0); printf("Page %d address is %4X\n",page,page1); } Considerations for Virtual Pages If you're using Power C, any supported BASIC compiler, Borland Pascal, or Turbo Pascal and need to create virtual pages, you must reduce the size of the far heap. Normally, these compilers allocate all remaining memory for the heap, which means fg_allocate will not be able to allocate memory for the virtual page. 160 Fastgraph User's Guide In BASIC programs, the SETMEM function reduces the size of the far heap. The BASIC versions of the Fastgraph example programs include the statement SetMemStatus& = SETMEM(-n) before calling FGallocate. This reduces the size of the far heap by n bytes. For a given video mode, the actual reduction needed is the number of virtual pages multiplied by the page size in that mode. Page sizes are listed at the beginning of this chapter, or you can use fg_pagesize to determine the page size for the current video mode. In Borland Pascal and Turbo Pascal, the $M compiler directive defines the maximum heap size in bytes. The Pascal versions of the Fastgraph example programs include the statement {$M 16384,0,16384} at the beginning of the examples that call fg_allocate. The third value in this list defines the maximum heap size at 16K bytes. This is suitable for most applications, but if your program uses the New or GetMem procedures to create dynamic variables that require more heap space, you'll need to increase the size beyond 16K. The far heap size for Power C programs is defined at link time. You must override the default heap size by including the option [,,16K] on the PCL command when you link a Power C program that uses fg_allocate. The value 16K is suitable for most applications, but if your program calls the farcalloc or farmalloc functions (or the calloc or malloc functions when using the large memory model), you may need to increase the far heap size beyond 16K. When you are using virtual pages, you should avoid using the fg_setvpage routine in sections of the program that require fast screen updates or animation sequences. This is because the PC and PS/2 video BIOS are only capable of displaying physical pages. To compensate for this restriction, Fastgraph exchanges the contents of a physical page with the requested virtual page. In other words, if page 1 is a virtual page and you make it the visual page, Fastgraph will exchange the contents of page 1 with whatever page was previously the visual page. This does not mean Fastgraph's page numbers change because Fastgraph also maintains an internal table containing video page addresses and exchanges the two corresponding table entries. As before, you would make page 1 the active video page if you wanted to write something to the visual page. About the only other potential problem when using virtual pages is what happens when you try to write to a non-existent video page (for example, if you write to virtual video page 1 before creating it with fg_allocate). In this case, Fastgraph simply redirects the video output to the visual page. Considerations for SuperVGA Pages If an program running in an SVGA graphics mode returns to text mode when the visual page is not page 0, some SVGA chipsets have problems the next time you try to run an SVGA application. We therefore recommend calling fg_setvpage(0) just before restoring the original video mode if an application performs page flipping in SVGA graphics modes. For example: Chapter 8: Video Pages and Virtual Buffers 161 old_mode = fg_getmode(); fg_svgainit(0); fg_setmode(25); . . . fg_setvpage(1); . . . fg_setvpage(0); /* add this line to be safe */ fg_setmode(old_mode); A few SVGA chipsets cannot set the display start address beyond the 16- bit capability provided by the CRT Controller, rendering fg_setvpage meaningless. Please refer to the READ.ME file for details. Logical Pages In addition to physical and virtual video pages, Fastgraph offers another class of video pages, called logical pages. You can create logical pages in any video mode. They can exist in conventional memory, expanded memory (EMS), or extended memory (XMS). However, they are not as versatile as physical or virtual pages because the only operations you can perform with logical pages are: * Copy an entire physical or virtual page to a logical page * Copy an entire logical page to a physical or virtual page * Copy an entire logical page to another logical page Three Fastgraph routines -- fg_alloccms, fg_allocems, and fg_allocxms -- create logical pages in conventional memory, expanded memory, and extended memory, respectively. All three routines have a single integer argument that specifies the page number by which the logical page will be referenced. The page number must be between 1 and 63 and must not reference a physical or virtual page. Their return value is 0 if the logical page is created, and negative otherwise (refer to the descriptions of these routines in the Fastgraph Reference Manual for a complete list of return values). As with virtual pages, use fg_freepage to release a logical page. Before you can create logical pages in expanded or extended memory, you must initialize these resources for use with Fastgraph. The fg_initems routine initializes expanded memory. To use expanded memory, you must have an Expanded Memory Manager (EMM) that conforms to the Lotus/Intel/Microsoft Expanded Memory Specification (LIM-EMS) version 3.2 or later. On 80386 and 80486 systems, the EMM386.EXE device driver supplied with DOS 5.0 can be used to treat some or all of extended memory as expanded memory. The fg_initxms routine initializes extended memory for use with Fastgraph. To use extended memory, you must have an XMS driver that conforms to the Lotus/Intel/Microsoft/AST eXtended Memory Specification version 2.0 or later, such as HIMEM.SYS. XMS drivers require an 80286, 80386, or 80486 system. The fg_initems and fg_initxms routines have no arguments and must be called after fg_setmode. Their return value is 0 if successful, and -1 if the required driver and resources are not present. 162 Fastgraph User's Guide In protected mode, the distinction between conventional, expanded, and extended memory disappears because DOS extenders essentially treat all system memory as conventional memory. For this reason, fg_initems and fg_initxms are not meaningful and thus always return -1 in the protected mode Fastgraph libraries. This effectively disables the fg_allocems and fg_allocxms routines, so you must create logical pages with fg_alloccms in protected mode. Example 8-10 illustrates the use of logical pages in a 320x200 color graphics mode. The program first tries to create a logical page in extended memory by calling fg_initxms and fg_allocxms. If the initialization or page creation fails, it then tries to create the page in expanded memory with fg_initems and fg_allocems. Should that fail, the program calls fg_alloccms to try to create the page in conventional memory. If it can't create the logical page at all, the program displays an error message and exits. Once the logical page is created, example 8-10 displays the word "test" in the middle of the visual page (page 0) and then uses fg_copypage to transfer the visual page contents to the logical page. Because this program runs in one of several different graphics modes, we use fg_findpage to choose the logical page number. After waiting for a keystroke, the program erases the visual page, waits for another keystroke, and copies the logical page contents back to the visual page. It then releases the logical page and exits. Example 8-10. #include <fastgraf.h> #include <stdio.h> #include <stdlib.h> void main(void); void main() { int new_mode, old_mode; int page, status; fg_initpm(); new_mode = fg_bestmode(320,200,1); if (new_mode < 0 || new_mode == 12) { printf("This program requires a 320 "); printf("x 200 color graphics mode.\n"); exit(1); } old_mode = fg_getmode(); fg_setmode(new_mode); page = fg_findpage(); status = fg_initxms(); if (status == 0) status = fg_allocxms(page); if (status < 0) { status = fg_initems(); if (status == 0) status = fg_allocems(page); } if (status < 0) status = fg_alloccms(page); if (status < 0) { Chapter 8: Video Pages and Virtual Buffers 163 fg_setmode(old_mode); fg_reset(); printf("Unable to create logical page.\n"); exit(1); } fg_setcolor(7); fg_rect(0,319,0,199); fg_setcolor(9); fg_locate(12,18); fg_text("test",4); fg_waitkey(); fg_copypage(0,page); fg_erase(); fg_waitkey(); fg_copypage(page,0); fg_waitkey(); fg_freepage(page); fg_setmode(old_mode); fg_reset(); } As mentioned before, the only functions you can perform with logical pages are copying physical/virtual pages to logical pages, logical pages to physical/virtual pages, or copying one logical page to another. The fg_copypage routine provides the only way to do this for logical pages. See Chapter 11 for more information about fg_copypage. Extended Video Pages One of the more frequent technical support questions we receive is "I have one megabyte of memory on my video card, why can I only use the first 256K?". The answer is simple: the standard EGA and VGA graphics modes have no way to address video memory beyond 256K. Accessing more memory requires SVGA bank switching techniques. This is analogous to the fact that you might have four megabytes of RAM on your system, but without an EMS/XMS memory manager, a DOS extender, or the like, all that memory won't do much good. Unfortunately, not all SVGA chipsets allow bank switching in non-SVGA video modes. For those that do, however, Fastgraph includes a feature called extended video pages. Extended pages provide access to all video memory in modes 13 to 18 and modes 20 to 23 instead of restricting access to the first 256K. This means, for example, that a 1MB SVGA card will allow 32 physical pages in mode 13 rather than the usual 8 pages. Extended pages are available with the following SVGA chipsets: * Ahead B * ATI 28800/38800/68800/88800 * Avance Logic 2000 series * NCR 77C22/77C32 * Oak OTI-067 164 Fastgraph User's Guide * Oak OTI-077 * Oak OTI-087 * Paradise WD90C11/WD90C30/WD90C31/WD90C33 * Tseng ET4000 Although extended pages are used in non-SVGA graphics modes, the method of accessing video memory above 256K is specific to each SVGA chipset. Thus, you must initialize Fastgraph's SVGA kernel (with fg_svgainit) before you can use extended pages. We haven't yet found a VESA implementation that supports extended pages, so you'll need to initialize the SVGA kernel for chipset- specific support. When writing applications that use extended video pages, you should make sure the user's SVGA chipset supports extended pages and that there is enough video memory for the number of pages required. First, make sure fg_svgainit successfully initializes the SVGA kernel. If so, check bit 2 of the fg_svgastat return value to see if the chipset supports extended pages. Finally, use fg_memory to insure that enough video memory is available for the number of video pages needed. The following table shows the number of video pages available in the graphics modes that support extended pages. Number of Pages With Mode 256K 512K 1MB 13 8 16 32 14 4 8 16 15 2 4 8 16 2 4 8 17 2 4 8 18 2 4 8 20 4 8 16 21 2 4 8 22 4 8 16 23 2 4 8 Note that when extended pages are not enabled, the video mode has the number of physical video pages listed in the 256K column. Some video modes do not provide the listed number of full video pages. For example, modes 17 and 18 normally have two video pages -- one full 640x480 page (page 0) and one partial 640x320 page (page 1). For extended pages, Fastgraph uses a page numbering scheme that maintains consistency with its standard page numbering. That is, when extended pages are available and mode 17 or 18 is used on a 1MB video card, the page numbers will range from 0 to 7, with the even-numbered pages being full pages and the odd-numbered pages being partial 640x320 pages. Similarly, in mode 22 pages 3, 7, 11, and 15 are partial (320x80); in mode 23 odd-numbered pages are partial (320x320). When you use Fastgraph's block transfer routines (fg_copypage, fg_restore, fg_save, fg_tcxfer, and fg_transfer) with extended pages, you must pass the source and destination page numbers to fg_defpages. This is needed because the two pages may reside in different SVGA banks, and bank switching is not performed in Fastgraph's non-SVGA code. The additional overhead of having the block transfer routines determine the bank numbers would impact the Chapter 8: Video Pages and Virtual Buffers 165 block transfer routines when extended pages are not being used. The fg_defpages routine determines the SVGA bank numbers in which the source and destination pages reside and then enables the corresponding banks for reading and writing. These banks remain in effect until you define new ones with fg_defpages or fg_setpage, so you may not need to call fg_defpages before every call to a block transfer routine. The fg_defpages routine has no effect unless extended pages are enabled. The following table shows the bank numbers for each video page in each graphics mode that supports extended pages. Bank 0 Bank 1 Bank 2 Bank 3 Mode Pages Pages Pages Pages 13 0-7 8-15 16-23 24-31 14 0-3 4-7 8-11 12-15 15 0-1 2-3 4-5 6-7 16 0-1 2-3 4-5 6-7 17 0-1 2-3 4-5 6-7 18 0-1 2-3 4-5 6-7 20 0-3 4-7 8-11 12-15 21 0-1 2-3 4-5 6-7 22 0-3 4-7 8-11 12-15 23 0-1 2-3 4-5 6-7 Next we'll present a short code sequence that calls fg_defpages only when needed in mode 13, where each group of 8 pages resides in its own SVGA bank. Calling fg_setmode enables bank 0 for reading and writing, so we don't need to call fg_defpages until we reference a page in one of the other banks (that is, a page numbered 8 or above). fg_svgainit(0); fg_setmode(13); /* enables bank 0 for reading and writing */ fg_copypage(0,1); fg_copypage(0,2); fg_defpages(0,1); /* page 10 is in bank 1 */ fg_copypage(2,10); fg_defpages(1,1); /* page 15 is in bank 1 */ fg_copypage(10,15); fg_setpage(0); /* enables bank 0 for reading and writing */ fg_erase(); fg_copypage(0,3); fg_defpages(1,0); /* page 15 is in bank 1 */ fg_copypage(15,4); Most mouse drivers know nothing about SVGA bank switching and non- standard video modes (that's why Fastgraph must hook its own mouse cursor control handlers into the mouse driver in XVGA and SVGA modes). As Fastgraph relies on the mouse driver for cursor control in modes 13 to 18, it's only possible to display the mouse cursor on video pages in the first SVGA bank (bank 0) in these modes. Note that this does not apply to modes 20 to 23, where Fastgraph controls the mouse cursor through its own handler. Some SVGA chipsets do not reset the read and write bank numbers back to zero when establishing a non-SVGA video mode. When a mode set operation clears video memory, such chipsets will clear the first video page in the last write bank selected. While fg_setmode does set the read and write banks to zero when extended pages are available, it cannot do this before setting the video mode, 166 Fastgraph User's Guide which is what normally would clear the screen. This may result in artifacts on page 0 after calling fg_setmode. The easiest way around this problem is to call fg_defpages(0,0) before restoring the original video mode in programs that use extended pages. Even this, however, does not clear video memory after a mode set when using extended pages with some SVGA chipsets. We therefore recommend calling fg_erase immediately after restoring the original video mode when using extended pages. Video Page Resizing Resizing is the process of changing the dimensions of a video page. It is available only in the native EGA graphics modes (modes 13 to 16), native VGA graphics modes (17 and 18), extended VGA modes (20 to 23), and SVGA modes (24 to 29). Resizing does not change the screen resolution, but instead increases the video page size so only part of the page is visible. For now, we'll just introduce resizing with a simple example, but in Chapter 13 we'll see its real power when we perform smooth panning. The Fastgraph routine fg_resize changes the dimensions of a video page. Its two integer arguments define the page width and page height, both in pixels. Example 8-11 runs in the 320x200 EGA graphics mode (mode 13). After establishing the video mode, it displays the word "resize" starting in column 38 of row 0. Because the characters extend beyond the last column of the row, they wrap to the next row. The program continues displaying this until you press a key. Then, it clears the screen and calls fg_resize to make the page size 640x200 pixels. Again the program displays the word "resize" starting in column 38 of row 0, but this time it does not wrap to the next row. This is because the resizing doubled the page width, which increased the number of character cells per row from 40 to 80. The characters that formerly wrapped to the next row now continue on an off-screen portion of the same row. Example 8-11. #include <fastgraf.h> #include <stdio.h> #include <stdlib.h> void main(void); void main() { int old_mode; fg_initpm(); if (fg_testmode(13,1) == 0) { printf("This program requires a 320 "); printf("x 200 EGA graphics mode.\n"); exit(1); } old_mode = fg_getmode(); fg_setmode(13); fg_setcolor(9); fg_locate(0,38); fg_text("resize",6); Chapter 8: Video Pages and Virtual Buffers 167 fg_waitkey(); fg_erase(); fg_resize(640,200); fg_setcolor(10); fg_locate(0,38); fg_text("resize",6); fg_waitkey(); fg_setmode(old_mode); fg_reset(); } The size of a video page is constrained only by the amount of video memory available and the addressability of the video mode. Increasing the video page size reduces the number of physical pages available proportionally. In mode 13, for example, increasing the page size from 320x200 to 640x400 reduces the number of video pages from 8 to 2. When you call fg_resize, the visual page must be page 0. If you have created any logical video pages, you must release them with fg_freepage before calling fg_resize, and then create them again afterward. If you have initialized the mouse (with fg_mouseini), joysticks (with fg_initjoy), expanded memory (with fg_initems), or extended memory (with fg_initxms), you should re-initialize these resources after calling fg_resize. In modes 13 to 18, most mouse drivers expect a fixed video page width, so the mouse cursor may become distorted after resizing video pages in these modes. When you call fg_resize, Fastgraph sets the clipping region to the new page limits. The fg_setmode routine re-establishes the dimensions of a video page to the default screen resolution for the selected video mode. The fg_resize routine has no effect when a virtual buffer is active. Depending on the dimensions passed to fg_resize, you may end up with a partial video page. Again, suppose we're using mode 13 and have changed the page size to 960x400 (this is six times the default page size). The original pages 0 to 5 now make up page 0, and original pages 6 and 7 now make up page 1. However, there is not enough video memory left on page 1 for a full 960x400 page. In this case, the number of pixel rows available on page 1 would be one- third the full page size, or 133 rows. This is because the total storage required by original pages 6 and 7 is one-third the total required for original pages 0 through 5. Extended video pages may be resized in modes 13-18 and 20-23, but the resulting pages must not cross SVGA bank boundaries. In mode 20, for instance, you normally have four 320x200 pages in each bank. You could change the video page size to 640x400, thereby having four larger pages, one in each bank. You could not, however, resize video memory to two 640x800 pages, as each page would span two banks. Preserving Video Page Contents Across Mode Switches Sometimes a graphics program may temporarily need to switch to another video mode. An example of this might be a graphical user interface (GUI) menuing system that includes "shell to DOS" as one of its options. When the user selects this option, the program must revert to a text video mode so the 168 Fastgraph User's Guide user will see the familiar DOS prompt when the shell executes. On leaving the DOS shell, the program returns to a graphics mode and should ideally restore the screen to what it was originally. When you establish a video mode with fg_setmode, Fastgraph clears all physical video pages and initializes its internal page tables as if no virtual or logical pages have been created. While it's not possible to preserve physical page contents across video mode switches, you can use Fastgraph's fg_getentry and fg_setentry routines to save virtual or logical page contents. The trick, so to speak, is using fg_getentry to save the virtual or logical page address and type before switching video modes. Then, when you return to the same video mode, you can use fg_setentry to restore the internal page tables to their previous state. This effectively makes the virtual or logical page accessible again. Example 8-12 illustrates this process. This program runs in video mode 18, the 640x480 16-color VGA graphics mode. After establishing this video mode, the program calls fg_alloccms to create a logical page in conventional memory. Next, it calls fg_getentry to save the address and type of the logical page just created. The first argument to fg_getentry specifies the page number (determined by fg_findpage); the next two arguments receive the page address and type. Page type codes used by fg_getentry and fg_setentry are: 0 = unallocated page 1 = physical page 2 = virtual page 3 = logical page in expanded memory (EMS) 4 = logical page in extended memory (XMS) 5 = logical page in conventional memory After this setup work, example 8-12 fills the screen with light blue pixels, draws a white box around the edge, and then waits for a keystroke. Before switching back to the original video mode (assumed to be mode 3), the program uses fg_copypage to copy the visual page contents to the logical page. This is necessary because we can only save virtual or logical page contents across video mode changes, not physical pages. In mode 3, the program prompts for a keystroke before returning to mode 18. Now we're ready to restore the previous contents of the visual page. Because the example program did not release the logical page, the memory is still allocated; Fastgraph just cannot access it. To solve this, the program calls fg_setentry to restore Fastgraph's internal page table entries for the original logical page number to what they were previously. Note how we use the same page address and type values in the call to fg_setentry that were returned earlier by fg_getentry. Now that the logical page is once again accessible, the program can use fg_copypage to copy its contents back to the visual page. With that explanation behind us, here is example 8-12. Example 8-12. #include <fastgraf.h> void main(void); void main() { int old_mode; Chapter 8: Video Pages and Virtual Buffers 169 int page, page_addr, page_type; fg_initpm(); old_mode = fg_getmode(); fg_setmode(18); page = fg_findpage(); fg_alloccms(page); fg_getentry(page,&page_addr,&page_type); fg_setcolor(9); fg_fillpage(); fg_setcolor(15); fg_box(0,639,0,479); fg_waitkey(); fg_copypage(0,page); fg_setmode(old_mode); fg_cursor(0); fg_setcolor(15); fg_text("Press any key.",14); fg_waitkey(); fg_setmode(18); fg_setentry(page,page_addr,page_type); fg_copypage(page,0); fg_waitkey(); fg_freepage(page); fg_setmode(old_mode); fg_reset(); } To keep the example as simple as possible, it does not test for availability of video modes, nor does it check if the logical page creation was successful. In a real application, of course, omitting these checks is not recommended. See example 8-17 for a version of this program that uses virtual buffers instead of logical pages. Controlling Page Allocation When Fastgraph creates virtual or logical pages in conventional memory with fg_allocate or fg_alloccms, it uses the DOS allocate memory service (function 48 hex of interrupt 21 hex). Some compilers allocate all or part of available conventional memory to a data structure called the heap or far heap. Memory allocation functions such as malloc handle their requests through an associated heap manager instead of through DOS services. If the heap manager controls all available memory, the DOS allocate memory service is essentially disabled because there will be no memory available to satisfy allocation requests. If the heap manager controls some but not all available memory, a conflict may arise between the heap manager and the DOS allocate memory service. To solve this problem, you can use the compiler's allocate far memory function to reserve memory for the virtual or logical page and then make the 170 Fastgraph User's Guide page known to Fastgraph with fg_setentry. The easiest way to determine the amount of memory to allocate is through the fg_pagesize function, which returns the page size in bytes (as a long integer) for the current video mode. To release the page, use fg_setentry with a page type of zero to mark the page as unallocated before actually freeing the memory. Pages created this way are not initially cleared because the allocated memory block contents are undefined. We recommend using fg_erase to set the page contents to the background color. Example 8-13 shows how to create a virtual page in real mode programs using these techniques instead of fg_allocate. It uses the farmalloc and farfree functions from the C run-time library for Borland compilers (the analogous Microsoft functions are _fmalloc and _ffree). Example 8-13 uses fg_pagesize and the Borland run-time library function farmalloc to create a virtual page in the 320x200 VGA/MCGA 256-color graphics mode. After allocating the memory, the program calls fg_setentry, passing it the page number (1), the segment portion of the memory block address (using the FP_SEG macro from the run-time library), and the code for a virtual page (2). Once the virtual page is set up, the program writes some text on the virtual page and then uses fg_copypage to display the virtual page contents on the visual page. Finally, it releases the page by calling fg_setentry (so Fastgraph knows the virtual page is gone) and the farfree run-time library function (to actually free the memory). The call to fg_setentry is not really needed in this instance because no further references are made to page 1. Example 8-13. #include <fastgraf.h> #include <dos.h> #ifdef __TURBOC__ #include <alloc.h> #else #include <malloc.h> #define farfree(p) _ffree(p) #define farmalloc(n) _fmalloc(n) #endif void main(void); void main() { int old_mode; unsigned page_addr; char far *buffer; old_mode = fg_getmode(); fg_setmode(19); buffer = farmalloc(fg_pagesize()+16); page_addr = FP_SEG(buffer) + (FP_OFF(buffer)+15)/16; fg_setentry(1,page_addr,2); fg_setpage(1); fg_erase(); fg_setcolor(9); fg_text("This is page 1.",15); fg_waitkey(); Chapter 8: Video Pages and Virtual Buffers 171 fg_copypage(1,0); fg_setentry(1,0,0); fg_waitkey(); farfree(buffer); fg_setmode(old_mode); fg_reset(); } Virtual Buffers Virtual buffers are blocks of conventional memory that you can treat as video memory. They are much more general than virtual pages, as they are supported in all graphics video modes and can be smaller or larger than the actual page size. An application may have up to 32 virtual buffers open simultaneously. Each virtual buffer has its own independent clipping limits, which default to the entire virtual buffer. Any program that uses virtual buffers must initialize the virtual buffer environment by calling fg_vbinit once, before it calls any of Fastgraph's other virtual buffer routines. The fg_vbinit routine has no arguments and no return value. In protected mode, and when using real mode compilers that support huge arrays (far arrays whose size may exceed 64K), use fg_vbdefine to create virtual buffers. The fg_vbdefine routine defines a block of previously allocated memory as a virtual buffer. Usually this memory is allocated dynamically with the malloc or farmalloc functions in C or C++, the GlobalAllocPtr function in protected mode Pascal, or the ALLOCATE statement in protected mode FORTRAN. The fg_vbdefine routine returns a handle by which the virtual buffer is referenced in other Fastgraph routines. Two related virtual buffer routines are fg_vbundef, which releases a virtual buffer handle, and fg_vbhandle, which returns the active virtual buffer handle (or -1 if no virtual buffer is active). The number of bytes required for a virtual buffer is simply its width in pixels multiplied by its height in pixels, regardless of the current video mode. The virtual buffer layout is equally simple. For instance, a 320x200 virtual buffer requires 64,000 bytes. The first 320 bytes represent the first row of the virtual buffer, the next 320 bytes represent the second row, and so forth. Within each of the 200 such rows, each of the 320 bytes represents one pixel. This means, for example, the (0,0) pixel in the virtual buffer would be at offset 0, the (2,0) pixel would be at offset 2, and the (2,1) pixel would be at offset 322. In general, the offset of the (x,y) pixel is given by the formula y*virtual_buffer_width + x. The method of dynamically allocating memory suitable for virtual buffers is compiler and environment dependent. When using 32-bit protected mode, the virtual buffer memory resides in the program's default data segment and is referenced through a standard near pointer. In 16-bit environments, the virtual buffer memory is a huge array and is referenced through a far pointer. The following examples illustrate how to allocate memory for a 640x400 virtual buffer for each compiler that supports dynamic allocation of huge memory blocks. 172 Fastgraph User's Guide For Borland C++ (16-bit), Turbo C++, Turbo C: char huge *buffer; buffer = (char huge *)farmalloc(640L*400L); For Microsoft C/C++, QuickC, Visual C++, 16-bit WATCOM C/C++: char huge *buffer; buffer = (char huge *)halloc(640L*400L,1); For 32-bit C/C++ compilers: char *buffer; buffer = (char *)malloc(640*400); For Borland Pascal 7 (protected mode): var buffer : pointer; buffer := GlobalAllocPtr(gmem_Fixed,Longint(640)*Longint(400)); For Microsoft FORTRAN PowerStation: INTEGER*1 BUFFER[ALLOCATABLE](:) INTEGER STATUS ALLOCATE(BUFFER(640*400),STAT=STATUS) Real mode BASIC, Pascal, and FORTRAN compilers have limited, if any, support for huge arrays. In these environments, use fg_vballoc to create virtual buffers. The fg_vballoc routine uses the DOS allocate memory service to reserve virtual buffer memory. The supported BASIC compilers and real mode Turbo Pascal normally assign all unused conventional memory to an area called the far heap. At best, this will cause DOS memory allocation requests to fail, but more often it creates memory conflicts that manifest themselves later in your application. To solve this problem, you must tell the compiler to reduce the size of the far heap. Real mode Pascal programmers must use the $M directive to reduce the far heap size by the total space needed for all virtual buffers. If you wanted to use a 640x400 virtual buffer, for example, the following $M directive would reduce the far heap size by 256,000 bytes: {$M 16384,0,256000} BASIC programmers must use the SETMEM function to reduce the far heap size by the total space needed for all virtual buffers, plus 16 bytes per virtual buffer. If you wanted to use a 640x400 virtual buffer in a BASIC program, the following SETMEM call would reduce the far heap size by 256,016 bytes: SetMemStatus& = SETMEM(-256016) After you're finished with a virtual buffer, its memory may be released using fg_vbfree. You should use fg_vbfree only with virtual buffers created with fg_vballoc and not those created with fg_vbdefine, and you cannot use it on the active virtual buffer. As fg_vballoc and fg_vbfree are needed for real mode only, they are not present in the Fastgraph protected mode libraries. For Chapter 8: Video Pages and Virtual Buffers 173 virtual buffers created with fg_vbdefine, just use your compiler's standard method for releasing dynamic memory blocks. Once a virtual buffer is defined, you can activate it with fg_vbopen. When a virtual buffer is active, most Fastgraph routines operate on that virtual buffer instead of video memory. This will continue until you call fg_vbclose, which redirects graphics operations back to the active video page. If you later want to activate the virtual buffer again, or if you want to switch to another virtual buffer previously created with fg_vbdefine, you can use fg_vbopen for this purpose. Two of Fastgraph's more important virtual buffer routines are fg_vbpaste and fg_vbcut. These routines move rectangular areas between the active virtual buffer and the active video page. The fg_vbcut routine copies an area from the active video page to the active virtual buffer. Similarly, fg_vbpaste copies an area from the active virtual buffer to the active video page. An especially useful property of fg_vbcut and fg_vbpaste is that they each remember the most recent active virtual buffer and video page. This feature makes it possible to move areas back and forth between a virtual buffer and video memory without continuously opening and closing the virtual buffer. The fg_vbpaste routine performs a simple translation for pixel values greater than the number of colors available in the current video mode. This could happen, for example, if you used fg_vbcut in a 256-color graphics mode and later used fg_vbpaste to display the virtual buffer contents in a 16-color graphics mode. Should this occur, fg_vbpaste will display pixels of color c in color c modulo n, where n is the number of colors available in the current video mode. At this point, some example programs should help clarify the use of virtual buffers. Our first example, 8-14, runs in the standard VGA/MCGA 320x200 256-color graphics mode (mode 19) and creates a virtual buffer twice as high and twice as wide as the screen size. This means we'll create a 640x400 virtual buffer requiring 256,000 bytes of conventional memory (conditional compilation sequences show how to allocate the virtual buffer memory for different compilers). If the virtual buffer was created successfully, the program calls fg_vbopen to activate the virtual buffer and then draws four 320x200 rectangles of different colors, one in each quadrant of the virtual buffer. It then uses fg_vbpaste to copy each rectangle to the active video page, followed by another call to show the center 320x200 portion of the virtual buffer (this will display equal parts of the four rectangles). Example 8-14. #include <fastgraf.h> #include <stdio.h> #include <stdlib.h> #ifdef __TURBOC__ #include <alloc.h> #else #include <malloc.h> #endif #define WIDTH 640 #define HEIGHT 400 174 Fastgraph User's Guide void main(void); void main() { int handle; int old_mode; #ifdef FG32 char *buffer; #else char huge *buffer; #endif /* initialize the video environment */ fg_initpm(); old_mode = fg_getmode(); fg_setmode(19); fg_vbinit(); /* set up a 640x400 virtual buffer */ #ifdef FG32 buffer = (char *)malloc(WIDTH*HEIGHT); #elif defined(__TURBOC__) buffer = (char huge *)farmalloc((long)WIDTH*(long)HEIGHT); #else buffer = (char huge *)halloc((long)WIDTH*(long)HEIGHT,1); #endif if (buffer == NULL) { fg_setmode(old_mode); fg_reset(); printf("Could not create the virtual buffer.\n"); exit(1); } handle = fg_vbdefine(buffer,WIDTH,HEIGHT); fg_vbopen(handle); /* draw a 320x200 rectangle in each virtual buffer quadrant */ fg_setcolor(9); fg_rect(0,319,0,199); fg_setcolor(10); fg_rect(320,639,0,199); fg_setcolor(11); fg_rect(0,319,200,399); fg_setcolor(12); fg_rect(320,639,200,399); /* paste each rectangle to the 320x200 active video page */ fg_vbpaste(0,319,0,199,0,199); fg_waitkey(); fg_vbpaste(320,639,0,199,0,199); fg_waitkey(); fg_vbpaste(0,319,200,399,0,199); fg_waitkey(); Chapter 8: Video Pages and Virtual Buffers 175 fg_vbpaste(320,639,200,399,0,199); fg_waitkey(); /* paste the center 320x200 subset of the virtual buffer */ fg_vbpaste(160,479,100,299,0,199); fg_waitkey(); /* close the virtual buffer */ fg_vbclose(); /* restore original video mode and exit */ fg_setmode(old_mode); fg_reset(); } Calling fg_vbclose before the final fg_setmode call is necessary because fg_setmode has no effect when a virtual buffer is active. If we didn't call fg_vbclose, the program would return to DOS in mode 19 instead of the original video mode. If you instead wanted to allocate the virtual buffer memory with fg_vballoc in example 8-14, the steps to create the virtual buffer would change as follows: /* set up a 640x400 virtual buffer */ handle = fg_vballoc(WIDTH,HEIGHT); if (handle < 0) { fg_setmode(old_mode); fg_reset(); printf("Could not create the virtual buffer.\n"); exit(1); } fg_vbopen(handle); If you create the virtual buffer with fg_vballoc, you also should use fg_vbfree to release the virtual buffer memory when it's no longer needed: /* close the virtual buffer */ fg_vbclose(); fg_vbfree(handle); Again, we recommend using fg_vballoc and fg_vbfree only with 16-bit compilers that do not provide easy methods for creating huge arrays. Example 8-15 illustrates the use of the fg_vbcut routine, which essentially performs the inverse operation of fg_vbpaste. That is, fg_vbcut copies a rectangular area from the active video page to the active virtual buffer. The program begins by drawing a 20x20 blue rectangle with a white border in the upper left corner of the active video page. After a keystroke, it sets up a 20x20 virtual buffer and calls fg_vbcut to copy the rectangle to 176 Fastgraph User's Guide the virtual buffer. The program then calls fg_vbpaste in a loop to display 16 copies of the virtual buffer contents across the bottom of the screen. Note that example 8-15 uses a virtual buffer that is just 20 pixels square, or 400 bytes total. Because it is so small, we chose to declare a 400-byte array for the virtual buffer instead of allocating its memory dynamically as in the previous example. Note also that because the virtual buffer array size is less than 64K bytes, we can declare it far instead of huge in 16-bit environments (huge arrays less than 64K are functionally equivalent to far arrays). Example 8-15. #include <fastgraf.h> #define WIDTH 20 #define HEIGHT 20 void main(void); #ifdef FG32 char buffer[WIDTH*HEIGHT]; #else char far buffer[WIDTH*HEIGHT]; #endif void main() { int handle; int old_mode; int x; fg_initpm(); old_mode = fg_getmode(); fg_setmode(19); fg_vbinit(); fg_setcolor(15); fg_rect(0,WIDTH-1,0,HEIGHT-1); fg_setcolor(9); fg_rect(1,WIDTH-2,1,HEIGHT-2); fg_waitkey(); handle = fg_vbdefine(buffer,WIDTH,HEIGHT); fg_vbopen(handle); fg_vbcut(0,WIDTH-1,0,HEIGHT-1,0,HEIGHT-1); for (x = 0; x <= 320-WIDTH; x += WIDTH) fg_vbpaste(0,WIDTH-1,0,HEIGHT-1,x,199); fg_waitkey(); fg_vbclose(); fg_setmode(old_mode); fg_reset(); } Chapter 8: Video Pages and Virtual Buffers 177 If you create a virtual buffer that is taller or wider than the page size (or perhaps both taller and wider), it's possible to perform virtual buffer scrolling. To achieve a scrolling effect, you generally just call fg_vbpaste iteratively such that the source region in the virtual buffer increments gradually, while the destination region on the active video page stays the same. Depending on the video mode and the size of the scrolling region, you may need to include a delay factor between fg_vbpaste calls so the area being scrolled doesn't appear to jump immediately to its ultimate destination. Example 8-16 performs virtual buffer scrolling. This example runs in the XVGA 320x200 256-color graphics mode (mode 20) and creates a 1000x50 virtual buffer using the method of example 8-14. The program fills the virtual buffer with a series of one-pixel wide rectangles, each 50 pixels high and in alternating colors. The actual scrolling takes place in the loop containing the two fg_vbpaste calls. We'll define a 100x50 area in the middle of the visual page, with horizontal extremes between 110 and 209, and vertical extremes between 75 and 124, as our scrolling region. We'll scroll the top half (25 pixels) of the virtual buffer from right to left while scrolling the bottom half from left to right. In other words, we'll be moving two 100x25 subsets of the virtual buffer through the scrolling region. The first fg_vbpaste call scrolls the top half of the virtual buffer. The starting x coordinate defining the region to transfer from the virtual buffer ranges from 0 to 900 in one-pixel increments, and the width of the transfer region is always 100 pixels. The height of the transfer region remains constant at 25 pixels (virtual buffer rows 0 to 24). The destination position is the upper half of the scrolling region on the visual page; its lower left corner is at x=110 and y=99. The second fg_vbpaste call, which scrolls the bottom half of the virtual buffer but in the opposite direction, behaves similarly. In this case, the starting x coordinate in the virtual buffer decreases from 900 to 0 in one- pixel steps, and its width is always 100 pixels. The height of the transfer region is again 25 pixels, but this time it uses rows 25 to 49 in the virtual buffer. The destination position is the lower half of the scrolling region on the visual page; its lower left corner is at x=110 and y=124. Example 8-16. #include <fastgraf.h> #include <stdio.h> #include <stdlib.h> #ifdef __TURBOC__ #include <alloc.h> #else #include <malloc.h> #endif #define WIDTH 1000 #define HEIGHT 50 void main(void); void main() { int handle; 178 Fastgraph User's Guide int old_mode; int x; #ifdef FG32 char *buffer; #else char huge *buffer; #endif /* initialize the video environment */ fg_initpm(); old_mode = fg_getmode(); fg_setmode(20); fg_vbinit(); /* fill the screen with light blue pixels */ fg_setcolor(9); fg_fillpage(); /* set up the virtual buffer */ #ifdef FG32 buffer = (char *)malloc(WIDTH*HEIGHT); #elif defined(__TURBOC__) buffer = (char huge *)farmalloc((long)WIDTH*(long)HEIGHT); #else buffer = (char huge *)halloc((long)WIDTH*(long)HEIGHT,1); #endif if (buffer == NULL) { fg_setmode(old_mode); fg_reset(); printf("Could not create the virtual buffer.\n"); exit(1); } handle = fg_vbdefine(buffer,WIDTH,HEIGHT); fg_vbopen(handle); /* fill the virtual buffer with a series of narrow rectangles */ for (x = 0; x < WIDTH; x++) { fg_setcolor(x); fg_rect(x,x,0,HEIGHT-1); } /* scroll the virtual buffer through a 100x50 window on the */ /* visual page, such that the top half scrolls left and the */ /* bottom half scrolls right */ for (x = 0; x < WIDTH-99; x++) { fg_vbpaste(x,x+99,0,24,110,99); fg_vbpaste(WIDTH-100-x,WIDTH-1-x,25,49,110,124); } fg_waitkey(); /* close the virtual buffer */ Chapter 8: Video Pages and Virtual Buffers 179 fg_vbclose(); /* restore original video mode and exit */ fg_setmode(old_mode); fg_reset(); } The last virtual buffer example program we'll present in this chapter is a version of example 8-12 modified to work with virtual buffers. Example 8-12 used a logical page in conventional memory to preserve the visual page contents across video mode switches, with some help from Fastgraph's fg_getentry and fg_setentry routines. Example 8-17 illustrates how you can accomplish the same thing with a virtual buffer. It runs in the 320x240 256- color graphics mode (mode 22) and uses a virtual buffer whose size is identical to the screen resolution. After creating the virtual buffer, the program fills the visual page with blue pixels and draws a white border around it. It then uses fg_vbcut to copy the screen contents to the virtual buffer. Like example 8-12, the program temporarily switches back to the original video mode and waits for a keystroke. It then reverts to mode 22 and uses fg_vbpaste to restore the screen contents. Example 8-17. #include <fastgraf.h> #include <stdio.h> #include <stdlib.h> #ifdef __TURBOC__ #include <alloc.h> #else #include <malloc.h> #endif void main(void); void main() { int handle; int old_mode; #ifdef FG32 char *buffer; #else char huge *buffer; #endif fg_initpm(); old_mode = fg_getmode(); fg_setmode(22); fg_vbinit(); #ifdef FG32 buffer = (char *)malloc(320*240); #elif defined(__TURBOC__) buffer = (char huge *)farmalloc(320L*240L); 180 Fastgraph User's Guide #else buffer = (char huge *)halloc(320L*240L,1); #endif if (buffer == NULL) { fg_setmode(old_mode); fg_reset(); printf("Could not create the virtual buffer.\n"); exit(1); } handle = fg_vbdefine(buffer,320,240); fg_setcolor(9); fg_fillpage(); fg_setcolor(15); fg_box(0,319,0,239); fg_vbopen(handle); fg_vbcut(0,319,0,239,0,239); fg_vbclose(); fg_waitkey(); fg_setmode(old_mode); fg_cursor(0); fg_setcolor(15); fg_text("Press any key.",14); fg_waitkey(); fg_setmode(22); fg_vbopen(handle); fg_vbpaste(0,319,0,239,0,239); fg_waitkey(); fg_vbclose(); fg_setmode(old_mode); fg_reset(); } Fastgraph includes other functions for working with virtual buffers, but we'll defer our discussion of them until later chapters. Summary of Video Page and Virtual Buffer Routines This section summarizes the functional descriptions of the Fastgraph routines presented in this chapter. More detailed information about these routines, including their arguments and return values, may be found in the Fastgraph Reference Manual. FG_ALLOCATE creates a virtual video page. The amount of memory required depends on the current video mode. This routine has no effect if it references a physical or logical video page. FG_ALLOCEMS creates a logical page in expanded memory (EMS). The amount of memory required depends on the current video mode and video buffer dimensions. This routine has no effect if it references a physical or virtual Chapter 8: Video Pages and Virtual Buffers 181 video page. In protected mode, fg_initems always fails, so fg_allocems is effectively disabled. FG_ALLOCXMS creates a logical page in extended memory (XMS). The amount of memory required depends on the current video mode and video buffer dimensions. This routine has no effect if it references a physical or virtual video page. In protected mode, fg_initxms always fails, so fg_allocxms is effectively disabled. FG_COPYPAGE transfers the contents of one video page to another. The pages may be physical, virtual, or logical video pages. If both pages are logical pages, they must exist in the same type of memory. This routine always applies to video pages, even when a virtual buffer is active. FG_DEFPAGES defines the SVGA banks for the source and destination page numbers when using Fastgraph's block transfer routines with extended video pages. FG_FINDPAGE finds an available video page number for a virtual or logical page. FG_FREEPAGE releases a virtual or logical video page created with fg_allocate, fg_alloccms, fg_allocems, or fg_allocxms. This routine has no effect if it references a physical video page, or a virtual page that was never created. FG_GETADDR returns the real mode segment address or protected mode segment selector for the active video page. FG_GETENTRY retrieves the type and address of a physical, virtual, or logical video page. This routine is useful for saving virtual or logical page contents across video mode changes. FG_GETPAGE returns the active video page number. FG_GETVPAGE returns the visual video page number. FG_INITEMS initializes expanded memory for use with Fastgraph's logical pages. In protected mode, the expanded memory initialization will always fail. FG_INITXMS initializes extended memory for use with Fastgraph's logical pages. In protected mode, the extended memory initialization will always fail. FG_PAGESIZE returns the video page size in bytes for the current video mode. The page size is always the video page size, even when a virtual buffer is active. FG_RESIZE changes the dimensions of a video page in EGA and VGA graphics modes. This function has no effect when a virtual buffer is active. FG_SETENTRY specifies the type and address of a physical, virtual, or logical video page. For logical pages, it further specifies if the page resides in conventional, expanded, or extended memory. This routine is useful for saving virtual or logical page contents across video mode changes, or for manual creation of virtual and logical pages. 182 Fastgraph User's Guide FG_SETPAGE establishes the active video page. It may be a physical or virtual page. FG_SETVPAGE establishes the visual video page. It may be a physical or virtual page. FG_VBALLOC creates a virtual buffer of the specified size. The memory for the virtual buffer is allocated automatically. This routine should be used instead of fg_vbdefine for real mode compilers that do not support huge memory blocks (that is, far blocks larger than 64K bytes). The fg_vballoc routine is not present in Fastgraph's protected mode libraries. FG_VBCLOSE closes the active virtual buffer and directs graphics output back to the active video page. FG_VBCUT copies a rectangular region from the active video page to the active virtual buffer. FG_VBDEFINE creates a virtual buffer of the specified size. FG_VBFREE releases a virtual buffer's handle and frees the memory allocated to a virtual buffer created with fg_vballoc. The fg_vbfree routine is not present in Fastgraph's protected mode libraries. FG_VBHANDLE returns the handle for the active virtual buffer, or -1 if no virtual buffer is active. FG_VBINIT initializes Fastgraph's virtual buffer environment. This routine must be called once, before any other routines that reference virtual buffers. FG_VBOPEN makes an existing virtual buffer the active virtual buffer. FG_VBPASTE copies a rectangular region from the active virtual buffer to the active video page. FG_VBUNDEF releases the handle associated with a virtual buffer.