TABLE OF CONTENTS vilintuisup.library/CloseVillageScreen vilintuisup.library/GetMemSize vilintuisup.library/IsVillageScreen vilintuisup.library/LockVillageScreen vilintuisup.library/OpenVillageScreen vilintuisup.library/OpenVillageScreenTagList vilintuisup.library/UnLockVillageScreen vilintuisup.library/VillageBestModeID vilintuisup.library/VillageBlitCopy vilintuisup.library/VillageGetBufAddr vilintuisup.library/VillageGetSegment vilintuisup.library/VillageModeList vilintuisup.library/VillageModeRequest vilintuisup.library/VillageRectFill vilintuisup.library/VillageScreenData vilintuisup.library/VillageSetDisplayBuf vilintuisup.library/VillageSetSegment vilintuisup.library/WaitVillageBlit vilintuisup.library/CloseVillageScreen vilintuisup.library/CloseVillageScreen NAME CloseVillageScreen - Close a special village screen SYNOPSIS CloseVillageScreen (screen) A0 void CloseVillageScreen (struct Screen *screen); FUNCTION This routine closes a screen, which was opened by OpenVillageScreen(). It is save to call this function with NULL or a screen pointer to a normal Intuition screen. In the last case the screen will not be closed. INPUTS a screen pointer, pointing to a screen structure. RESULTS EXAMPLE look at the example given by OpenVillageScreen(). NOTES SEE ALSO OpenVillageScreen(), LockVillageScreen(), UnLockVillageScreen() BUGS vilintuisup.library/GetMemSize vilintuisup.library/GetMemSize NAME GetMemSize - get the memory size of the graphic board SYNOPSIS size = GetMemSize(screen) D0 A0 ULONG GetMemSize(struct Screen *screen); FUNCTION This routine returns the graphic board memory size in bytes. Please supply a NULL as screen pointer to get the board size. This is necessary for future enhancements. A call to LockVillageScreen() is not necessary. This function will always return the size of the on board RAM. Not the autoconfig size and not the window size, if the board runs in segmented mode. On a Picasso-II-board you will get as result only 1048576 or 2097152. INPUTS a screen pointer, currently NULL RESULTS ULONG - size of board memory in bytes. NOTES In the future for a screen pointer the function will return the size the screen occupies in memory. SEE ALSO BUGS vilintuisup.library/IsVillageScreen vilintuisup.library/IsVillageScreen NAME IsVillageScreen - determine the type of a screen SYNOPSIS is_village = IsVillageScreen(screen) D0 A0 BOOL IsVillageScreen(struct Screen *screen); FUNCTION This routine returns TRUE, if the screen represented by the screen pointer is a village screen, FALSE otherwise. A call to LockVillageScreen() is not necessary. INPUTS a screen pointer, pointing to a screen structure. RESULTS TRUE - if the corresponding screen is a village screen and was opened with a call to a vilintuisup.library function. FALSE - otherwise NOTES SEE ALSO BUGS vilintuisup.library/LockVillageScreen vilintuisup.library/LockVillageScreen NAME LockVillageScreen - lock screen to prevent screen manager movements SYNOPSIS address = LockVillageScreen(screen) D0 A0 APTR LockVillageScreen(struct Screen *screen); FUNCTION This routine locks the screen. You should only draw into the screen if you locked it before. It is save to call this function with a screen pointer, which does not belong to a village screen. If the screen is a special village screen, LockVillageScreen() returns the address of the first byte in the screen bitmap. According to the color depth of the screen a pixel occupies 1, 2 or 3 bytes. One line occupies the number of pixel per line multiplied with the number of byte per pixel. ByteInOneLine = BytePerPixel * Screen.Width For further documention see "basics.doc". INPUTS struct Screen *screen a screen pointer, pointing to a screen structure. RESULTS APTR address address of the first byte in the screen bitmap. EXAMPLE look at the example given by OpenVillageScreen(). NOTES IMPORTANT: Since version 2.4 LockVillageScreen() and UnLockVillageScreen() work nested. Pay attention how often do you lock and unlock a screen. Every lock must match an unLock, otherwise the screen will be locked forever. SEE ALSO OpenVillageScreen(), CloseVillageScreen(), UnLockVillageScreen() BUGS vilintuisup.library/OpenVillageScreenTagListp.library/OpenVillageScreenTagList NAME OpenVillageScreenTagList - Open a special village screen SYNOPSIS Screen = OpenVillageScreenTagList(tagitemarray) D0 A0 struct Screen *OpenVillageScreenTagList(struct TagItem *ti); FUNCTION This routine opens a screen, which will be displayed on the graphic board. It works similar to OpenVillageScreen, but has some advantages. Please use only this function in the future. You have all possibilities offered by OpenVillageScreen() and much more functionality. With this function you can open autoscroll screens, double buffering screens, you have nothing to know about available screen modes or depths. In the easiest way call it without any value: s = OpenVillageScreenTagList(NULL). As a result you will get the biggest screen available for 24 bit. If all went OK, you will get a pointer to a normal screen structure. If something went wrong, you will get NULL. Please close screens, which you opened with OpenVillageScreen() or OpenVillageScreenTagList() only with CloseVillageScreen(). You will loose a lot of RAM, if you close a screen with CloseScreen(). To determine, what screen you want to be opened by this function, you have to supply TagItems. OpenVillageScreenTagList() will accept only one tag item array, where all tag items should be placed. Available tag items are TAVIS_SCREEN_HEIGHT TAVIS_SCREEN_WIDTH TAVIS_SCREEN_DEPTH Use these items to specify the dimensions of the new screen. TAVIS_SCREEN_MODEID If you have already a DisplayID, specify this with TAVIS_SCREEN_MODEID. If you supply a DisplayID and some dimensions with the above tags, but you want to get the best id for the specified dimensions, supply TAVIS_BEST_MODEID with TRUE or FALSE. This causes OpenVillageScreenTagList to look for a better DisplayID than the supplied one. To open a screen behind all other, specify this with TRUE or FALSE: TAVIS_OPEN_BEHIND You can open autoscrolling screens with TAVIS_AUTOSCROLL and TRUE or FALSE. When using this, you have to supply a DisplayID, the height, width and depth of the new screen. If you want to open a screen that is bigger than the biggest available, you will get the biggest available. This screen might be smaller than the screen you really need. If this is not what you want, specify TAVIS_ALLOW_FALLBACK with FALSE and you will get NULL as result, if the requested screen is bigger than the biggest available. If you want to here about why you got NULL as result, supply TAVIS_ERROR_CODE with a pointer to an ULONG. There you will find one of the following error codes: TAVIS_ERR_OK /* all O.K. */ TAVIS_ERR_NOMEM /* not enough memory for screen */ TAVIS_ERR_MODE_NOT_AVAILABLE /* Mode with ModeID not present */ TAVIS_ERR_DIM_TOO_BIG /* dimensions are too big */ TAVIS_ERR_DIM_TOO_DEPTH /* color depth is too big */ TAVIS_ERR_DOUBLE_BUF_TOO_BIG /* not enough memory for doublebuf */ TAVIS_ERR_CANT_OPEN_SCREEN /* original OpenScreen failed */ To open a double buffer screen, supply TAVIS_DOUBLE_BUFFER with TRUE. The resulting screen is twice as high than requested. Please refer to VillageSetDisplayBuf() to switch between the buffers. Last, you can supply an old struct Dimension pointer with TAVIS_DM_STRUCT Refer to OpenVillageScreen() for that. INPUTS a pointer to a tag item array or NULL RESULTS struct Screen *screen a pointer to a struct Screen structure or 0L, if the screen could not be opened EXAMPLE /* take a look to the various new example programs */ NOTES SEE ALSO CloseVillageScreen(), LockVillageScreen(), UnLockVillageScreen(), vilintuisup.h screenmode.h BUGS vilintuisup.library/OpenVillageScreen vilintuisup.library/OpenVillageScreen NAME OpenVillageScreen - Open a special village screen (obsolete) SYNOPSIS Screen = OpenVillageScreen(dimensions) D0 A0 struct Screen *OpenVillageScreen (struct Dimensions *dm); FUNCTION THIS FUNCTION IS AN OLD ONE. PLEASE USE OpenVillageScreenTagList() instead. This routine opens a screen, which will be displayed on the graphic board. If the screen could be opened, the function returns the address of the screen structure. If the call fails, OpenVillageScreen() returns 0. OpenVillageScreen() performs all checks and will open the screen only, if the monitor is able to display the desired resolution and colors. INPUTS struct Dimensions *dm. You have to fill in dm->Width a number between 320 and 4096 dm->Height a number betwenn 240 and 4096 dm->Depth a number of 8, 15, 16 or 24 RESULTS struct Screen *screen a pointer to a struct Screen structure or 0L, if the screen could not be opened EXAMPLE #include #include "vilintuisub.h" void HandleVillageCard() { struct Screen *ScreenPointer; struct Dimensions dm = { 0, 800, 600, 8 }; UBYTE *FirstByteInScreen; if (ScreenPointer = OpenVillageScreen(&dm)) { FirstByteInScreen = LockVillageScreen(ScreenPointer); // ... do some actions to show the user something nice things UnLockVillageScreen(ScreenPointer); // ... wait for user input bevor closing the screen CloseVillageScreen(ScreenPointer); } else { PutStr("Can't open the desired screen\n"); } } NOTES Do not decompile or disassemble this function. The internal function calls and algorithm will change in the future. SEE ALSO CloseVillageScreen(), LockVillageScreen(), UnLockVillageScreen(), vilintuisup.h BUGS vilintuisup.library/UnLockVillageScreen vilintuisup.library/UnLockVillageScreen NAME UnLockVillageScreen - unlock screen to allow screen manager movements SYNOPSIS UnLockVillageScreen(screen) D0 A0 void UnLockVillageScreen(struct Screen *screen); FUNCTION This routine unlocks a locked screen. After unlocking please don't draw into the screens bitmap. It is save to call this function with a screen pointer, which does not belong to a village screen. INPUTS a screen pointer, pointing to a screen structure. RESULTS -- (void) EXAMPLE look at the example given by OpenVillageScreen(). NOTES IMPORTANT: Since version 2.4 LockVillageScreen() and UnLockVillageScreen() work nested. Pay attention how often do you lock and unlock a screen. Every lock must match an unLock, otherwise the screen will be locked forever. SEE ALSO OpenVillageScreen(), CloseVillageScreen(), LockVillageScreen() BUGS vilintuisup.library/VillageBlitCopy vilintuisup.library/VillageBlitCopy NAME VillageBlitCopy - Move memory using the graphic board blitter SYNOPSIS result = VillageBlitCopy(screen,vilcopyrec) D0 A0 A1 LONG VillageBlitCopy(struct Screen *s, struct VilCopyRecord *rec); FUNCTION This routine is complex. It uses the graphic board blitter. The blitter can manipulate, copy and fill memory regions located on the graphic board memory. In addition the source (x)or destination region can be located in the Amiga system memory (one region - not both). To do the action the blitter should do for you, you have to supply several information. This has to be done using a VilCopyRecord structure: struct VilCopyRecord { UBYTE *SrcAdr; /* Source address start */ UBYTE *DestAdr; /* Destination address start */ UWORD SrcPitch; /* Width of source area in pixels */ UWORD DestPitch; /* Width of destination area in pixels */ UWORD Width; /* Rectangle width in pixels to deal with */ UWORD Height; /* Rectangle height in pixels to deal with */ ULONG ROP; /* Blit Raster Operation - see below */ }; SrcAdr and DestAdr are normal Amiga memory addresses. The pitches specify the width of the area you copy from/to, e.g. if the rectangle you want to copy is located on a screen with a width of 1024 pixel, SrcPitch has to be 1024. If the screen you want to copy to has a width of 800 pixel, DestPitch has to be 800. Width and Height are the width and height of the rectangle you deal with. ROP can be: VIL_ZERO /* Clear all bits */ VIL_ONE /* Set all bits */ VIL_SRCCOPY /* Copy Source to Destination */ VIL_NOTSRCCOPY /* Copy inverted Source to Destination */ VIL_SRCAND /* logical AND Source with Destination */ VIL_NOTSRCAND /* logical AND inverted Source with Destination */ VIL_SRCPAINT /* logical OR Source with Destination */ VIL_MERGEPAINT /* logical OR inverted Source with Destination */ VIL_SRCINVERT /* logical EXOR Source with Destination */ VIL_NOTSRCINVERT /* logical EXNOR Source with Destination */ VIL_SRCERASE /* logical AND Source with inverted Destination */ VIL_NOTSRCERASE /* logical AND inverted Source with inverted Destination */ VIL_SRCORNOT /* logical OR Source with inverted Destination */ VIL_NOTSRCORNOT /* logical OR inverted Source with inverted Destination */ VIL_DSTINVERT /* invert Destination */ The routine tests the parameter block. If anything is not ok, it will do nothing and will return 0. Overlapping rectangles are handled correctly by VillageBlitCopy(). With the call of "VillageBlitCopy()" you start a blit. You have to use WaitVillageBlit() do determine the end of the blit. This feature allows you to use the CPU while the blitter is working (see exmaple below). IMPORTANT: VillageBlitCopy() will immediatly return 0 if the screen you want to act on is not the "FirstScreen" of Intuition. In other words: You can use the blitter only if you can see the screen you want to blit to/from. You have to call LockVillageScreen()/UnLockVillageScreen() to use the blitter, VillageBlitCopy() does not. INPUTS a screen pointer, pointing to a Screen structure. a pointer, pointing to a VilCopyRecord structure. RESULTS 0 - if something goes wrong -1 - if no blitter is available 1 - if all was o.k. EXAMPLE /* this example implements a falling rectangle like the one in */ /* 8BitBlitterDemo */ struct VilCopyRecord vilcopy = { 0, /* Source address in memory */ 0, /* Destination address in memory */ 1024, /* Width of source display in pixels */ 1024, /* Width of destination display in pixels */ 256, /* Width of rectangle box in pixels */ 256, /* Height of rectangle box in lines */ VIL_SRCCOPY /* Copy all */ }; Forbid(); /* screen must be in displaymem !!! */ ScreenToFront(s); /* bring the screen to front */ memstart = LockVillageScreen(s); /* snap the memory address */ Permit(); /* allow other taks to do what they want */ WaitVillageBlit(); /* wait for previous blitter actions to quit */ /* create a nice background scenery */ for (y=0; y < 256; y++) { memset(memstart+(y*3*1024),y,1024*3); } /* set the source address, it is the first line */ xpos = 200; vilcopy.SrcAdr = memstart+xpos; /* for each loop iteration calculate the DestAdr and blit */ for (y=1; y < 121; y++ ) { (UBYTE *)vilcopy.DestAdr = memstart + xpos + (ULONG) ((float)(y*y)*0.034534653f) * vilcopy.SrcPitch; VillageBlitCopy(s,&vilcopy); WaitVillageBlit(); /* the old DestAdr is the new SrcAdr */ (UBYTE *)vilcopy.SrcAdr = (UBYTE *)vilcopy.DestAdr; } UnLockVillageScreen(s); // don't forget this NOTES Maximum value for VilCopyRecord.Width is 2048 bytes (2048 pixels in Chunky Pixel mode, 1024 pixels in HiColor mode, 682 pixels in TrueColor mode). Minimum value is 2 bytes. Maximum value for VilCopyRecord.Height is 1024 pixels in all modes. Maximum values for VilCopyRecord.SrcPitch and VilCopyRecord.DestPitch are 4096. SEE ALSO WaitVillageBlit(), LockVillageScreen(), UnLockVillageScreen() BUGS Blits from display memory to system memory does not work in version 1.1 and 1.2. vilintuisup.library/VillageRectFill vilintuisup.library/VillageRectFill NAME VillageRectFill - Fills a rectangle using the graphic board blitter SYNOPSIS result = VillageRectFill(screen,vilfillrec) D0 A0 A1 LONG VillageRectFill(struct Screen *s, struct VilFillRecord *rec); FUNCTION This routine works similar to VillageBlitCopy(). Instead of copying it fills a rectangle with a specified color using the blitter. This is 10 times faster than it can be done by the CPU. Please remember that this function will only work, if the screen you wants to work on, is in front of all other screens and is a village screen (Use "IsVillageScreen()" to determine this). To fill the rectangle, you have to supply several information. This has to be done using a VilFillRecord structure: struct VilFillRecord { UBYTE *DestAdr; /* Destination address start */ UWORD DestPitch; /* Width of destination area */ UWORD Width; /* Rectangle width to deal with */ UWORD Height; /* Rectangle height to deal with */ LONG Color; /* special, see below */ }; DestAdr is a normal Amiga memory address. The pitch specifies the width of the area the rectangle should be filled, e.g. if the rectangle you want to fill is located on a screen with a width of 1024 pixel, DestPitch has to be 1024. If the screen you want to fill a rectangle has a width of 800 pixel, DestPitch has to be 800. Width and Height are the width and height of the rectangle you deal with in pixel (not BYTE!). Color has different meanings, depending on the color depth of the screen. If in Chunky Pixel mode, Color must have a value between 0 ... 255. In both HiColor or TrueColor mode the value is a merged rgb-value. The lowest significant byte contains the blue value, the next byte the green value, the third the red value. The most significant byte should be zero. A value like 255 is a very intensive blue. The routine tests the parameter block. If anything is not ok, it will do nothing and will return 0. With the call of "VillageRectFill()" you start a fill. You have to use WaitVillageBlit() do determine the end of the blit. This feature allows you to use the CPU while the blitter is working (see exmaple below). "VillageRectFill()" starts with a WaitVillageBlit() before performing the fill operation. IMPORTANT: VillageRectFill() will immediatly return 0 if the screen you want to act on is not the "FirstScreen" of Intuition. In other words: You can use the blitter only if you can see the screen you want to blit to/from. You have to call LockVillageScreen()/UnLockVillageScreen() to use the blitter, VillageRectFill() does not. INPUTS a screen pointer, pointing to a Screen structure. a pointer, pointing to a VilCopyRecord structure. RESULTS 0 - if something goes wrong -1 - if no blitter is available 1 - if all was o.k. EXAMPLE /* this example does random rectangles like the program */ /* 8BitFillDemo.c */ { struct VilFillRecord vilfill = { 0, /* DestAdr, will be set later */ 1024, /* Width of destination display */ 256, /* Width of rectangle box */ 256, /* Height of rectangle box */ 0 /* Color of rectangle */ }; /* This is important for the blitter use */ Forbid(); /* screen must be in displaymem !!! */ ScreenToFront(s); /* bring screen to front */ memstart = LockVillageScreen(s); Permit(); /* stop on CTRL-C */ while (CheckSignal(SIGBREAKF_CTRL_C) == 0) { xpos = rand() % s->Width; ypos = rand() % s->Height; vilfill.DestAdr = (APTR)(memstart +(xpos + (ypos * s->Width))); vilfill.DestPitch = s->Width; vilfill.Width = rand() % (s->Width-xpos); vilfill.Height = rand() % (s->Height-ypos); vilfill.Color = rand() % 256; VillageRectFill(s,&vilfill); // does it's own WaitVillageBlit() inside } UnLockVillageScreen(s); } NOTES Maximum value for VilFillRecord.Width is not longer limited. It was limited until version 2.3. This is gone. Maximum value for VilCopyRecord.Height is 1024 pixels in all modes. Maximum value for VilFillRecord.DestPitch is 4096. SEE ALSO VillageBlitCopy(), WaitVillageBlit(), LockVillageScreen(), UnLockVillageScreen() BUGS The operation had a bug in both HiColor modi. This is gone since version 2.0. This function will fail, if you wants to fill a rectangle greater than 1024 lines in height. vilintuisup.library/WaitVillageBlit vilintuisup.library/WaitVillageBlit NAME WaitVillageBlit - wait for blitter to finish SYNOPSIS WaitVillageBlit() void WaitVillageBlit(void) FUNCTION This routine waits until the blitter on the graphic board has finished its work. This is a busy wait in the current implementation! If your actions allow a concurrent processing of data, you can use the blitter and the CPU at the same time. First start a blit, second do actions with the CPU and third call WaitVillageBlit(). INPUTS -- (void) RESULTS -- (void) EXAMPLE /* this demo source fills a 1024x768 wide screen with zeros and ones */ struct VilCopyRecord vilcopy = { 0, /* Source offset from beginning of displaymem */ 0, /* Dest offset from beginning of displaymem */ 1024, /* Source pitch == width of display */ 1024, /* Destination pitch == width of display */ 1024, /* Width of rectangle box */ 768, /* Height of rectangle box */ VIL_ZERO /* Zero all bytes */ }; /* first get the address of the first byte in the screen */ (UBYTE *)vilcopy.DestAdr = LockVillageScreen(s); for(y=768;y > 0;y-=4) { WaitVillageBlit(); // wait for blitter to finish VillageBlitCopy(s,&vilcopy); // o.k. start Blitter (UBYTE *)vilcopy.DestAdr += 2050; // do now the calculation vilcopy.Width -= 4; // for the next loop iteration vilcopy.Height -= 4; // while the blitter is ... if (vilcopy.ROP == VIL_ZERO) // ... working { vilcopy.ROP = VIL_ONE; } else { vilcopy.ROP = VIL_ZERO; } } /* all o.k., free the screen */ UnLockVillageScreen(s); NOTES Blitting will only work, if the screen you wish to blit on is the frontmost screen, that means the screen must be located in the graphic board memory. SEE ALSO LockVillageScreen(), UnLockVillageScreen(), VillageBlitCopy() BUGS vilintuisup.library/UnLockVillageScreen vilintuisup.library/UnLockVillageScreen NAME VillageModeRequest - open a ScreenMode requester with village modes SYNOPSIS DisplayID = VillageModeRequest(tagarray) D0 A0 ULONG VillageModeRequest(struct TagItem *ti); FUNCTION This function opens a window with a listview in it. The listview contains all display modes available or only some of them, depending on the tag items you supply with this function. The listview will only contain village display modes, not normal Amiga modes like NTSC:HighRes. There are several TAG_ITEMS with the listed functionality: TAVIS_MINDEPTH TAVIS_MAXDEPTH TAVIS_MINHEIGHT TAVIS_MAXHEIGHT TAVIS_MINWIDTH TAVIS_MAXWIDTH These tags works like a filter. Which each tag you specify the minimal or maximal dimension a screenmode must have, to be displayed in the listview the user will see. TAVIS_MINDEPTH is the minimum color depth like 8, 15, 16 or 24 (bits). If the tag array you supply for VillageModeRequest contains something like this ... TAVIS_MINDEPTH, 16, ... you will only see resolutions with a color depth of 16 or 24 bits -- unless you specify a TAVIS_MAXDEPTH tag. If you want to build up a complex list, please take a look to the explanations for TAVIS_CUSTOM_LIST later in this decription. TAVIS_WINDOWTITLE TAVIS_LISTVIEW TAVIS_OKGADGET TAVIS_CANCELGADGET TAVIS_HELP_TEXT TAVIS_ABOUT_TEXT TAVIS_NOTICE_TEXT TAVIS_CHOOSE_TEXT You may customize any text in the Mode Request to your needs. Just select the TAG you want and a text you want, e.g. ... TAVIS_WINDOWTITLE, "My 16 & 24 bit GLU Viewer", ... TAVIS_MENU_QUIT TAVIS_MENU_HELP TAVIS_MENU_ABOUT TAVIS_MENU_PROJECT You may customize any menu text to your needs. Just select the TAG you want and a text you want in the language you want, e.g. ... TAVIS_ABOUT, "This is a special program by me!", ... TAVIS_CUSTOM_LIST After this TAG you have to supply a pointer to an Exec List Header. The list must be filled by a call to VillageModeList(). VillageModeList() will accept the TAVIS_MIN_#? and TAVIS_MAX_#? as well as VillageModeRequest(). This enables you to create more complex filters for screenmode. E.g., you can create a ModeRequest with 8 bit and 24 bit resolutions. INPUTS a pointer to a tag array, may be NULL or a pointer to a TAG_DONE tag. RESULTS ULONG DisplayID The DisplayID may (!) only contain a valid DisplayID, if the user has chosen the OK button. Otherwise the funtion will return INVALID_ID. INVALID_ID is nonzero. Please keep this in mind. Something like if (VillageModeRequest(...)) WILL NOT WORK!!! You have to call the function this way if (VillageModeRequest(...) != INVALID_ID) EXAMPLE /* * Search for all 24 bit color depth resolutions. For this * set TAVIS_MINDEPTH to 24, so you will get only resolutions * with 24 bit or higher. If you want exactly only 24 bit res... * supply TAVIS_MAXDEPTH with a value of 24, too. */ struct TagItem ti1[] = { { TAVIS_MINDEPTH, 24 }, { TAG_DONE, 0 } }; /* * The second TagItem specifies getting only resolutions * with 8 bit maximum and a customlist. The custom list * pointer will be set later by a call to VillageModeList. */ struct TagItem ti2[] = { { TAVIS_MAXDEPTH, 8 }, { TAVIS_CUSTOM_LIST, 0L }, { TAG_DONE, 0 } }; /* * here starts the program ... */ struct Library *VilIntuiBase; struct Library *IntuitionBase; int main(int argc, char *argv[]) { struct List *l; // pointer to a List struct Remember *Key = 0; // a key for Alloc-/FreeRemember ULONG DisplayID = 0L; // for the value we want to get if (VilIntuiBase = OpenLibrary("vilintuisup.library",2)) {if (IntuitionBase = OpenLibrary("intuition.library",37)) { /* * first get only a list with special nodes for the * ScreenMode requester */ if (l = VillageModeList(&Key,ti1)) { /* * Now, set the pointer to the list in ti2. */ if (ti2[1].ti_Tag == TAVIS_CUSTOM_LIST) { ti2[1].ti_Data = l; } /* * O.K., all set. Display the ScreenMode requester */ DisplayID = VillageModeRequest(ti2); /* * You will get a valid ID only, if the User clicked on O.K. */ if (DisplayID != INVALID_ID) { Printf("Display ID ist %8lx\n",DisplayID); } /* * THAT IS IMPORTANT: * Last, free the memory allocated by VillageModeList */ if (Key != 0) { FreeRemember(&Key,TRUE); } } else { PutStr("Can't read screenmode database?!?\n"); } CloseLibrary(IntuitionBase); } CloseLibrary(VilIntuiBase); } return 0; } NOTES If you supply a custom list, please create the list via VillageModeList(). The node structure may be extended in the future. SEE ALSO VillageModeList(), OpenVillageScreenTagList() vilintuisup/screenmode.h BUGS The request is not reentrant. To prevent system crashes -- which occur until version 2.3, if you opened the request twice -- this will not occure since version 2.4. A semaphore acts like a sequences: only one request will be open at the same time. The next requester will open, if the first one will have gone. vilintuisup.library/VillageScreenData vilintuisup.library/VillageScreenData NAME VillageScreenData - returns internal screen or general info SYNOPSIS ULONG VillageScreenData(screen, tag) D0 A0 D0 ULONG VillageScreenData(struct Screen *screen, ULONG Tag); FUNCTION With this function you can get special infos depending on the tag you supply as the second parameter. You have to set the first parameter, if you want to get a screen info. Those tags begin with a TAVIS_SD_SCREEN_#?. TAVIS_SD_SCREEN_DEPTH To get the screen depth of a screen. The screen must be a pointer to a village screen. Please check this first with a call to IsVillageScreen(). TAVIS_SD_SCREEN_MEMSIZE To get the size of the memory the screen occupies. If you requested a double buffering screen this is more than for a normal screen. TAVIS_SD_CARD_MEMSIZE Returns the amount of memory like GetMemSize() in Byte. TAVIS_SD_CARD_SEGMENTED Returns TRUE, if the graphic board works segmented, FALSE otherwise. INPUTS struct Screen *screen pointer to a screen structure ULONG TAG one of the TAGs above RESULTS data depending from the requested data EXAMPLE ULONG depth; if (IsVillageScreen(s) { depth = VillageScreenData(s,TAVIS_SD_SCREEN_DEPTH); Printf("The screen depth from screen %s is %ld\n", s->Title, depth; } else { Printf("The Screen %s is NOT a village screen\n", s->Title); } NOTES SEE ALSO GetMemSize(), VillageGetSegment(), "vilintuisup/Screenmode.h" BUGS vilintuisup.library/VillageGetSegment vilintuisup.library/VillageGetSegment NAME VillageGetSegment - get the active segment or ~0 SYNOPSIS segnum = VillageGetSegment() D0 ULONG VillageGetSegment(void); FUNCTION If the graphic board works in segment mode -- with a memory window of 64 KByte -- you will get the number of the active segment after calling this function. If the graphic board works non segmented, you will get ~0 (= 0xFFFFFFFF) as a result to this call. INPUTS -- (void) RESULTS ~0 - board works non segmented segnum - number o active segment NOTES SEE ALSO VillageSetSegment() BUGS vilintuisup.library/VillageGetBufAddr vilintuisup.library/VillageGetBufAddr NAME VillageGetBufAddr - get the address from a double buffer screen SYNOPSIS address = VillageGetBufAddr(screen,bufnumber) D0 A0 D0 ULONG VillageGetBufAddr(struct Screen *screen, ULONG bufnumber); FUNCTION If you are using double buffer screens, it might be usefull to know, where the two buffers start in memory. After a lock using LockVillageScreen() you can call this function with a screen pointer and a number to get the needed address. Valid bufnumbers are only 0 or 1. If you supply bigger numbers, you will get NULL as a result. The address is only valid if the screen is a village double buffer screen and you are holding a lock to that screen. INPUTS a pointer to a screen structure of a village double buffer screen the buffer number, valid numbers are 0 and 1 RESULTS NULL - if the screen is not valid or the number is out of range address - the address of the buffer otherwise NOTES No check will be made, if the screen is a double buffer screen. Please check it yourself. SEE ALSO VillageSetDisplayBuf(), OpenVillageScreenTagList() BUGS vilintuisup.library/VillageSetDisplayBufintuisup.library/VillageSetDisplayBuf NAME VillageSetDisplayBuf - Set active buffer for double buffer screens SYNOPSIS VillageSetDisplayBuf(screen,bufnumber) A0 D0 void VillageSetDisplayBuf(struct Screen *screen, ULONG bufnumber); FUNCTION To set the active buffer, if you are using double buffering for a screen, use this function to switch between the to buffers. Valid bufnumbers are only 0 or 1. If you supply bigger numbers, nothing will happen. If you try to switch from a buffer to a buffer which is already active, nothing will happen. If you call this function on non-double buffer screen, nothing will happen. The switch will be done by hardware the time the raster line will build up a new screen. INPUTS a pointer to a screen structure of a village double buffer screen the buffer number, valid numbers are 0 and 1 RESULTS -- (void) NOTES No check will be made, that the screen is a double buffer screen. Please check it yourself. This function uses MoveScreen() internaly. Don't use MoveScreen() on double buffer screens. The results will be quiet interesting! SEE ALSO VillageGetBufAddr(), OpenVillageScreenTagList() BUGS vilintuisup.library/VillageModeList vilintuisup.library/VillageModeList NAME VillageModeList - get a list of available special modes SYNOPSIS list = VillageModeList(memorykey,tagarray); D0 A0 A1 struct List *VillageModeList(struct Remember **key, struct TagItem *ti); FUNCTION Sometimes it is usefull to get a complete list (or only some) of all available display modes of the graphic board. For this you can use the function VillageModeList(). You have to supply the address of a pointer as a memory anchor and a pointer to TagItem array. Please initialise the pointer 'key' to NULL before you call this function. After use of the created list you can free the list and all nodes with a call to FreeRemember(&key); All TAVIS_MIN_#? and TAVIS_MAX_#? tag items will be accepted by this function. For a description of these tag items please look at the description of VillageModeRequest(). As a result you will get NULL, if there are no modes available that suit your needs. If there are modes, you will get a pointer to a list header as a result. The list will contain one or more nodes. Each node has the type "struct VilCustomModeNode" struct VilCustomModeNode { struct Node Node; char Text[VIL_MODENAMELEN]; ULONG DisplayID; UWORD Width; UWORD Height; UWORD Depth; }; For each mode you can find the name in "Node.ln_Name" or "Text", die ModeID in "DisplayID", and the width, height and depth of that mode. The structure definition can be found in "vilintuisup/screenmode.h". Please remember that all nodes and the list header are allocated via AllocRemember(). They can only be freed via FreeRemember. This function is mainly intended to be used in conjuntion with VillageModeRequest(). INPUTS a pointer to "struct Remember *" pointer. a pointer to a TagItem array. May be NULL or a pointer to a TAG_DONE tag. RESULTS NULL - if there are no entries or something went wrong a pointer to a "struct List *" list header. EXAMPLE /* please look at the example by VillageModeRequest **/ NOTES Remember the size of VIL_MODENAMELEN if you create a node by your own. SEE ALSO vilintuisup/screenmode.h, VillageModeRequest() BUGS vilintuisup.library/VillageSetSegment vilintuisup.library/VillageSetSegment NAME VillageSetSegment - set the active segment SYNOPSIS VillageSetSegment(segnum) D0 void VillageSetSegment(ULONG segnum); FUNCTION If the graphic board works in segment mode -- with a memory window of 64 KByte -- a call to VillageSetSegment() sets the active segment to the supplied number. If the graphic board works non segmented, a call to this function has no effect. INPUTS ULONG segnum - number of segment RESULTS -- (void) NOTES SEE ALSO VillageGetSegment() BUGS vilintuisup.library/VillageBestModeID vilintuisup.library/VillageBestModeID NAME VillageBestModeID - get the best ID with filter tags SYNOPSIS DisplayID = VillageBestModeID(tagarray); D0 A0 ULONG VillageBestModeID(struct TagItem *ti); FUNCTION If you only want to get a DisplayID from screen dimensions, try this function. You can -- you do not have to -- supply a TagItem array with one or more TagItems. The function calculates a ViewMode the desired screen will fit into or the biggest screen available for a given color depth. The result is a DisplayID or INVALID_ID. It will NEVER be NULL! Valid TagItems are TAVIS_SCREEN_HEIGHT the desired height TAVIS_SCREEN_WIDTH the desired width TAVIS_SCREEN_DEPTH the desired depth If you do not supply all three items, the function will assume ~0 as a replacement for missing tag items. As a result of this the function will return the biggest screen in 24 bit (color depth) if you supply NULL as TagItem pointer. If you want to get a bigger screen than available, you will get the biggest screen available in the desired color depth. This might be smaller than necessary. To get the smallest screen available for a given color depth, set TAVIS_SCREEN_WIDTH and TAVIS_SCREEN_HEIGHT to zero. It is strongly advised to supply a color depth. In the future there might be graphic boards with more than 24 bit or less than 8 bit minimum color depth. Today you know nothing about the organisation of this -- today not available -- new modes. INPUTS a pointer to a tag array, may be NULL or a pointer to a TAG_DONE tag. RESULTS INVALID_ID - if something went wrong DisplayID - a valid display ID, which will never be NULL EXAMPLE #include #include #include #include #include #include #include #include "vilintuisup.h" #include "ScreenMode.h" #include "vilintuisup/vilintuisup_protos.h" struct TagItem ti0[] = { { TAG_DONE, 0 } }; struct TagItem ti1[] = { { TAVIS_SCREEN_DEPTH, 24 }, { TAG_DONE, 0 } }; struct TagItem ti2[] = { { TAVIS_SCREEN_DEPTH, 16 }, { TAG_DONE, 0 } }; struct TagItem ti3[] = { { TAVIS_SCREEN_DEPTH, 8 }, { TAVIS_SCREEN_HEIGHT, 800 }, { TAG_DONE, 0 } }; struct TagItem ti4[] = { { TAVIS_SCREEN_DEPTH, 8 }, { TAVIS_SCREEN_HEIGHT, 2000 }, { TAG_DONE, 0 } }; struct Library *VilIntuiBase; void PrintIDDimensions(ULONG ID) { DisplayInfoHandle Handle; struct DimensionInfo dimension; if (ID != INVALID_ID) { if (Handle = FindDisplayInfo(ID)) { if (GetDisplayInfoData(Handle,(UBYTE *)&dimension, sizeof(dimension),DTAG_DIMS,0)) { Printf("DisplayID: %8lx, Depth: %2ld, Width: " "%4ld, Height: %4ld\n", ID, dimension.MaxDepth, dimension.Nominal.MaxX+1, dimension.Nominal.MaxY+1); } else { Printf("Can't get DimensionInfo for ID %8lx\n",ID); } } else { Printf("Can't find DisplayInfo for ID %8lx\n",ID); } } else { PutStr("INVALID_ID is not a valid ID!\n"); } } int main(int argc, char *argv[]) { ULONG DisplayID = INVALID_ID; if (VilIntuiBase = OpenLibrary("vilintuisup.library",2)) { PrintIDDimensions(VillageBestModeID(ti0)); PrintIDDimensions(VillageBestModeID(ti1)); PrintIDDimensions(VillageBestModeID(ti2)); PrintIDDimensions(VillageBestModeID(ti3)); PrintIDDimensions(VillageBestModeID(ti4)); CloseLibrary(VilIntuiBase); } else { PutStr("Can't open vilintuisup.library\n"); } return RETURN_OK; } NOTES In the future a value <>0 for the screen pointer will return the size, the screen occupy in memory. SEE ALSO OpenVillageScreenTagList(), VillageModeList(), vilintuisup/screenmode.h BUGS .