Flamingo Plus/4 emulator for the Amiga External video driver documentation version 1.0 Friday 07.07.98 Intro ----- As became an "industry standard" Flamingo have external driver for video. That is a must because of the mess of different Amiga video drivers, cards and other trouble makers, and because of my limited possibilities and abilities. I am not perfect, God knows, even you can write a much faster video driver than mine. To build a video driver for Flamingo is as easy as a pie. You have to obey some rules anyway, those are included in this text. Before you start coding anything please (PLEASE!) read this doc carefully! Format ------ As usual too external video drivers are executables, and loaded by LoadSeg, when needed. To allow this you have to start with these lines (in that case, when anybody start it without Flamingo): moveq.l #0,d0 rts Then you have to continue with a simple pattern for identify: dc.b 'FLAMINGOXVD' Next byte is for identify video-driver level. This should be for now: dc.b '1' That was all about identify. Level will be raised if any changes should become in driver format later. Then a little table coming up: dc.l Name_of_video_driver ; -> pointer dc.l Author_of_video_driver ; -> pointer dc.w Version ; -> not pointer, but the number dc.w Revision ; -> not pointer, but the number Name and Author strings should be zero terminated. And finally the table of pointers to the functions: dc.l drv_Init dc.l drv_Done dc.l drv_Configure dc.l drv_OpenScreen dc.l drv_CloseScreen dc.l drv_Refresh Functions --------- At first: keep in mind code must be reentant. No global variables, memory array etc... Of course you have to hold your data somewhere, and this would be a memory segment allocated by your driver, and it will be given as parameter for every function of yours. (Let's call handler.) This handler should be given back by drv_Init_driver function. Flamingo will never change this piece of memory. (Of course not, it knows nothing about it, even not the length.) You can mess up all registers Flamingo saves his regs before your routine will be called. All subroutines called by a JSR, so all have to end with RTS. Okay, let's go on the functions: * drv_Init * Inputs: A0 - pointer to library bases A1 - public screen (eg. Workbench) Outputs: D0 - handler D1 - ptr to message You can do anything in this function, initialisations, open libraries etc. As input the routine will get a structure of longwords: dc.l graphics_library_base dc.l dos_library_base dc.l intuition_library_base dc.l gadtools_library_base dc.l asl_library_base Do not open provided libraries (Graphics, Dos, Intuition, Gadtools, Asl), use these bases! As output give back any number in D0 except zero (0). This will be your handler, you may ignore it, if you need no room to store something (I can hardly believe). Zero output means your driver was failed to initialize itself. (Missing driver, library etc.) In this case you can send an error message by D1. It will be displayed in any way. (If D0 not zero D1 will be ignored.) * drv_Done * Inputs: A0 - handler Deallocate all system resources you have ever allocated. Do not call drv_CloseScreen from this routine, it will be called before! Don't forget deallocate all memory, even used by handler! * drv_Configure * Inputs: A0 - handler You can open an interface, if your driver needs any configuration. All library bases (gadtools too) was given in drv_Init, do not reopen these! The other parts of Flamingo are hanging on while your configuration is running. Important! If this field in the structure contains zero, then configure button will be disabled in Flamingo's GUI. (Please put zero here, if you have nothing to configure.) * drv_OpenScreen * Inputs: A0 - handler A1 - screen_params Output: D0 - valid IDCMP port address D1 - ptr to message D2 - ptr to allocated chunky buffer D3 - modulo for the chunky buffer (LONG) Open your screen by this routine. Screen_params is a structure to dc.w xsize dc.w ysize dc.l palette ;ptr to the palette xsize is screen width and always an even multiple of 16, ysize is screen height, palette a pointer to an array of RGB values on 8 bits each (R1,G1,B1,R2,G2,B2,...) contains 121 colors. About screen format can be found more in refresh part. If your routine was not able to open its screen, then send back 0 in D0, and you can also send some zero terminated string in D1. (drv_Done called in this case too!) If open was successful send a valid IDCMP port address in D0, D1 will be ingored. The only IDCMP required by Flamingo is IDCMP_RAWKEY, other messages will be discarded. Don't forget to allocate chunky buffer for the emulated screen! Give back this address in D2. (Size is xsize*ysize in bytes.) There is an easy way on graphcards doing double buffered chunky screens, by allocating both buffer and changing displayed at drv_Refresh. (Find out more at there.) I added modulo for the chunky screen, as it might be useful for native chunky displays. * drv_CloseScreen * Input: A0 - handler Close your screen by this routine. (Or hide, if you prefer, but watch out on hide, drv_OpenScreen can be recall after drv_CloseScreen! And don't forget deallocate your screen on drv_Done...) * drv_Refresh * Input: A0 - handler Output: D0 - (next) chunky screen Last, but not least here you have to refresh your screen. If your driver is a graphcard driver which can set up chunky 8 bit screen, you have to do almost nothing in this routine, but for an AGA driver this is the most hardest part. After your screen was opened, your palette was loaded, you have to convert 8 bit chunky data to your screen. In the emulator screen colors between 0-127 had been used. You can see: only 7 bit is enough. Chunky format: one pixel is one byte, 0th. bit is LSB, 6th. bit is MSB and 7th. is always 0 (hopefully, you can depend on this). After finishing the conversion (or anything you do), give back the (next) address of chunky screen in D0. (You can do easly double buffering on graphcards.) If you use the same chunky buffer again, then give back that address. I see no reason of an MMU based driver, emulator uses line-based screen emulation, and it refreshes all lines on screen at this time. That's all, any questions mail to me: racs@fs2.bdtf.hu