Club Amiga de Montreal

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

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 493.lha / Cburst_dev / DEVELOP1.DOC.pp / DEVELOP1.DOC

Wrap

Text File | 1991-04-06 | 22.9 KB | 589 lines

Here is a list of preliminary functions to access and control a ColorBurst screen:- Firstly a list of the routines, then an explanation of thier access and functions. Please note that this is a *Very* preliminary set of routines and a full set of 'MAC Quickdraw' style library of routines is being compiled at the moment. The new library will be accessable as an Amiga Sytem Intuiton style library and will support a full set of draw routines including:- Rectangle, areafills, polygons, elipse and circle and curves. all of the ColorBurst library of routines automatically clip if it exceeds screen boundarys and have relative X,Y offset as well. The total direction of the ColorBurst routines will eventually be aimed at fully automatic virtual memory operation as standard capability (allowing you to have for example an 8000 * 6000 pixel 24 bit screen as a superbitmap allocated to either FAST memory or the HARD-DRIVE and fully automatically operate on it as though it was all in memory). I will have a lot more time to thoroughly compile a large library of routines after the full release of ColorBurst. I have written the routines in 100% assembly language for compactness and speed. 'C' progrmmers should find the Interface and linking fairly strait- forward. If you are unsure about the variable passsing, have a look at the file "CB_Link_Stuff.i". Source code for the routines are file "CB_Lib.src" and are assembly language. These routines will be refined and optomised continually and at present are not neseccarily in their most graceful state at this moment. Please note that a few of these routines were written specific to the paint program.these are routines that deal with the ColorPalette selector and the Amiga Menu. Also Direct intuition support will be provided soon to allow use of the Intuiton library for Gadgets, reqeusters and IntuiText. Also possibly for windowing support. I will discuss using the Amiga's Blitter and Copper as well as Intuition interfacing in a later document. Here is the list of current Developers rotuines as of 26-Feb-91:- [1] OpenScreen24 ;Open a 24 bit ColorBurst screen [2] CloseScreen24 ;close a ColorBurst screen [3] DrawRGB ;Draw a pixel at X,Y with RGB value [4] ReadRGB ;Read a pixel at X,Y with RGB value [5] SetControl ;control video modes and output [6] SetRGB ;Setup the 24 bit palette map [7] SetData ;Set CoPRO control data [8] SetCoPRO ;Set a list of CoPROcessor intructions [9] SetLoadAddress ;Set display load address (scroll & animate) [10] Update_Palette_CoPRO ;select update to palette or coprocessor [11] Chng_DataLine ;change address of data interface [12] Chng_NoWrt_DataLine [13] Select_Col_CoPRO [14] Set_Control_Bit ;set a bit in the control register [15] Set_Menu_Position ;Set paint program menu position [16] Set_DMA_Ratio ;Control the screen DMA update speed [17] Load_Menu_Palette ;Set the colors for the Amiga Menu [18] Set_Menu_Bitmap ;Link in Menu bitplanes into copper list Conventions of passing data to or from the calling program:- Most direct parameters are passed from the stack. These values are not pushed onto the stack but are placed just below the current stack pointer (the stack grows downwards) this is the convention used by most 'C' compilers. Here is an example from 'C' :- { unsigned char ScreenFlags; long *CB_Screen; ScreenFlags = 3; /* Open a Hi-res 24 bit screen */ CB_Screen = OpenScreen24(ScreenFlags); } in compiled code the values are passed back and forth like this:- Compiled code:- move.l (sp),a0 add.l #4,a0 ;get past stack pointer move.b ScreenFlags,(a0) ;pass screen flags value bsr _OpenScreen24 ;do it! move.l a0,*CB_Screen ;return screen structure pointer .... .... .... ;and so on some of the parameters for a lot of these rotuines are passed or recieved from the ColorBurst's screen structure. An example would be the routine 'DrawRGB'. The X and Y as well as the relative X & Y and RGB values are to be directly altered in the ColorBurst screen structure. here is a 'C' example of DrawRGB:- { .... ;Your code goes here .... CB_Screen.Pen_X = My_X; /* set the Draw X location */ CB_Screen.Pen_Y = My_Y; CB_Screen.Rel_X = My_Rel_X; /* set relative locations */ CB_Screen.Rel_y = My_Rel_y; CB_Screen.Red_Value = My_Red /* Red value */ CB_Screen.Red_Value = My_Green /* Green value */ CB_Screen.Red_Value = My_Blue /* Blue value */ DrawRGB(); /* Plot the pixel */ .... .... } This may appear as a bit of an indirect way of accessing the rotuine, but I have purposely done this to prevent redundant data from being passed to increase speed where possible. If I was drawing a line in the same color for every pixel, I would not want to pass the R, G & B value with every 'DrawRGB' call. Another example would be during a brush paste using 'DrawRGB' I would just want to adjust the Relative X & Y location before calling my brushpaste function instead of having to pass it or calculate it with the X & Y values in my Brush Paste routine. This also gives you the ability to 'see' what was the last values you passed or to directly pass the values on from one routine to another without having to pass data. You could do a 'ReadRGB' Then adjust the Relative X & Y and do a 'DrawRGB' without having to Update the R, G, & B values to retain pixel color. Assembly language calls are very straitforward. Just Place the parameters past the stack pointer and call the routine. Examine the file 'CB_Link_Stuff.i' to see how I am passing the data. Here is the explanation and calling parameters of each routine. ____________________________________________________________________________ [1] OpenScreen24: This routine opens up a 24 bit screen in the requested resolution and returns a long pointer to the ColorBurst screen structure. It returns -1 if failed. The OpenScreen routine automatically senses if a Genlock is installed. Different screens are required for PAL and NTSC. Bit 3 of the Open flags specifies PAL or NTSC. Here is a list of the display flags:- Bit 3 0 = PAL, 1 = NTSC Bit 2 0 = Non overscan, 1 = Overscan Bit 1 0 = Non Interlaced, 1 = Interlaced Bit 0 0 = Lo Resolution, 1 = High Resolution Please keep unused bits 0 for upward compatibility. Note:- You may not have enough chip memory for some of the display resolutions. If you don't, It will still go ahead and open the screen as long as you have at least 50% of the requested memory, You will need to examine the Variable in the ColorBurst screens structure called 'Actual_Height' to find if you have lost any and how may lines becuase of lack of Amiga memory. It is important to remember that 24 bit screens do require 24 bits of actual memory, which can add up to a lot of memory. The future Virtual memory handler will take care of this no matter how much memory you have available. also ColorBurst does have 1.5 megabytes of Video Ram onboard. Pictures can be 'Loaded' in components. Each component of the ColorBurst display is 4 actual bitplanes of data. This means that a full overscan hi-res image could be loaded on an Amiga 1000 with 256k of chip ram if it was loaded Component by Component (Which is NO slower in load time). A different Component loader will be available shortly or you can use some tricks with this routine. to open the screen pass an 8 bit byte value containing your flags. The ColorBurst screen structure pointer is passed as a long value in register A0. a value of -1 is returned here if the screen could not be opened. Here is the ColorBurst Screen Structure. ;Struct CBurstScreen: Screen_Width dc.w 0 ;Width of current screen Screen_Height dc.w 0 ;Requested height of current screen Actual_Height dc.w 0 ;Actual Height of current screen Mode dc.w 0 ;Screen Modes (Genlock, Interlace) PAL_NTSC dc.b 0 ;PAL or NTSC Modes (PAL = 1; NTSC = 0) Lo_Hi dc.b 0 ;Lo or Hi-res $ff = Hi-res Virtual_Mem dc.l 0 ;Amount of Virtual memory if required Mouse_X dc.w 0 ;Current X mouse position (resolution depend) Mouse_Y dc.w 0 ;Current Y mouse position (resolution depend) Raw_Mouse_X dc.w 0 ;Raw Mouse position (not affected by res) Raw_Mouse_Y dc.w 0 ;Raw Mouse position (not affected by res) Pen_X dc.w 0 ;Current X position of Pen Pen_Y dc.w 0 ;Current X position of Pen Rel_X dc.w 0 ;Relative X offset value Rel_Y dc.w 0 ;Relative Y offset value Red_Value dc.b 0 ;Red color Data Green_Value dc.b 0 ;Green color Data Blue_Value dc.b 0 ;Blue color Data Kluge_Pad dc.b 0 ;Oh no! a Kludge filler! Screen_Planes dc.w 0 ;Number of Amiga Bitplanes in screen (12/24) BitMaps dc.l 0 ;Pointer to Bitmap structure Menu_BitMaps dc.l 0 ;Amiga Menu Bitmap structure (5 bitplanes) Color_BitMaps dc.l 0 ;Color palette bitmap struct DMA_Ratio dc.b 0 ;Screen Update Ratio (for greater speed) DMA_Enable dc.b 0 ;Bit 0 on enables screen DMA & screen update ___________________________________________________________________________ [2] CloseScreen24 This will close the current ColorBurst screen. No values are returned or passed. ___________________________________________________________________________ [3] DrawRGB This will draw a pixel with the RGB values at any X,Y location. Relative X,Y offsetting is incorporated as well as automatic clipping if out of screen boundarys. All values are passed and returned in the ColorBurst Screen Structure. The Values that are used or affected in the ColorBurst screen structure are- Pen_X ;The X position to plot pixel Pen_Y ;The Y position to plot pixel Rel_X ;Relative offset for X Rel_Y ;Relative offset for Y Red_Value ;Byte value for Red Green_Value ;Byte value for Green Blue_Value ;Byte value for Blue Just set the values that you are changing for the pixel operation. ____________________________________________________________________________ [4] ReadRGB This will Read a pixel with the RGB values at any X,Y location. Relative X,Y offsetting is incorporated as well as automatic clipping if out of screen boundarys. All values are passed and returned in the ColorBurst Screen Structure. The Values that are used or affected in the ColorBurst screen structure are- Pen_X ;The X position to plot pixel Pen_Y ;The Y position to plot pixel Rel_X ;Relative offset for X Rel_Y ;Relative offset for Y Red_Value ;returns Byte value for Red Green_Value ;returns Byte value for Green Blue_Value ;returns Byte value for Blue Just set the values that you are changing for the pixel operation. ____________________________________________________________________________ [5] SetControl Sets the Video Control registers. I will go into this in more detail later this does not need to be called for 'Normal' 24 bit screens but has been included to give greater control over the ColorBurst Hardware. This will be initialised with the correct data for a standard 24 bit screen update when the screen is opened. A thorough understanding of how ColorBurst operated will be needed to have successful control of this register. usage: (long) address of control line to modify (word) Data to write to that control line Here is a table of the Bit functions anyway - **** Control Bit Name Function -------------------------------------------------------------------- Bit 15 Reserved Reserved for future expansion (Low) Bit 14 BWR2 Active high writes to Blue bank 2 Bit 13 GWR2 Active high writes to Green bank 2 Bit 12 RWR2 Active high writes to Red bank 2 Bit 11 FIELD Odd or Even field display Bit 10 BWR2 Active high writes to Blue bank 1 Bit 9 GWR2 Active high writes to Green bank 1 Bit 8 RWR2 Active high writes to Red bank 1 Bit 7 S0 Video Mode Control Bit 6 AUTO Auto display sync when high Bit 5 Col/Cop Update (0)Palette or (1)Coprocessor Bit 4 WREN Enable Write to Col/Cop when high Bit 3 VALID3 must be a 1 for a CBurst frame Bit 2 VALID2 must be a 0 for a CBurst frame Bit 1 VALID1 must be a 1 for a CBurst frame Bit 0 VALID0 must be a 0 for a CBurst frame ___________________________________________________________________ There can be as many as 14 of these Control lists involved with the functions of updating and controlling a 24 bit screen. _____________________________________________________________________________ [6] SetRGB This sets the Color Register Palette table for Red, Green and Blue. Adjusting the color palette allows you to fade in and out pictures, do complex color cycling and strobing or other effects such as glow or image intensifying. You could even smoothly fade from a postive to a negative Image or do solarized effects on a 24 bit image. The overall white balance of the picture can easily be adjusted with this as well. the Palette has 256 variables each for Red, Green, and Blue. It operates in 24 bit mode as a Color Lookup table. any output value can be assigned to a data input value. $20 of screen data for red could actually be assigned the value $ff for example. The Red, Green and Blue values are independant of each other. This routine is not at all optimised and I will be providing a faster routine shortly. The values are passed directly as follows:- (byte) Register to modify (byte) Red value (byte) Green value (byte) Blue value No return values. Note 1: The palette is already initialised with a gray scale (true 24 bit output scale) when the screen is opened. Note 2: The palette update must be enabled by a call to 'Update_Palette_CoPRO' becuase only the Palette or the CoPROcessor can be updated within a field period (1/60th of a second for NTSC or 1/50th for PAL) You must arbitrate which you would like to update by calling 'Update_Palette_CoPRO' Note 3: for Glitch free palette update we have provided a double buffered palette update option allowing you to write a new palette whilst displaying the old palette. Alternatively you could just enable the update to the CoPROcessor whilst updating the palette then enable update to the Palette with the routine 'Update_Palette_CoPRO' ____________________________________________________________________________ [7] SetData Sets some of the Video Control Registers associated with the CoPROcessor and video curcuitry. here is a list of each of the variables and thier functions (byte) ColAddress Sets the palette load address writing the first and cosequetive palette data (ideal for easy high speed color cycling or palette Special Effects) specify an Address of 0 for normal operation. (byte) PixelMask Allows you to mask out specific bits of video data before they go through the palette. (great for Animation using less colors or hiding menu selections etc.) a logic 1 in this register allows the corresponding bit to be enabled in the palette lookup. $00 will let no picture show at all except backgound color, and $ff will let the full picture show in 24 bits. (byte) ControlReg The Control register that controls what video mode you are operating in. Black level pedistal (0 IRE or a 7.5 IRE) and 6 or 8 bit output DAC operation. (for compatibility with 6 bit IBM VGA mode) I will need to go into more detail in another document later on the video modes. ____________________________________________________________________________ [8] SetCoPRO This will setup a coprocessor instruction on the specified scan line. The CoPROcessor is a custom VLSI that allows many powerful functions not available in most 24 bit systems. Some of the capabalitys of the CoPRO- cessor are Double Buffered Animation in 24 bits, Page flipped Animation, Smooth fullscreen glitch free realtime scrolling (Horizontal and vertical), Changing video modes on any scan line, Changing resolutions, Changing the priority and mixing of Amiga graphics with ColorBurst graphics, Dual ColorBurst displays, 2 full stencils for control of video Priority allowing you to specify regions of ColorBurst to appear over Amiga graphics with the stencil. All of these functions can be controlled and modified on any scan line. The CoPROcessors functions are very powerful, but there is a lot to discuss in regard to controlling these functions. I will need to go into detail in another document. here is the calling convention:- (word) scan line to place instruction (byte) Instruction data No return value. Here is a list of the bit functions in each instruction byte Bit # Name Function ------------------------------------------------------------------- Bit 7 AddressLoad* loads the Video Address counters when low Bit 6 S1 Video mode control Bit 5 LO/HI Low = Low resolution; High = Hi-res Bit 4 PM Priority Mode, 1 = use stencil for priority Bit 3 PR Video Priority, 0 = Amiga, 1 = ColorBurst Bit 2 DD Dual display, 0 = active, 1 = single display Bit 1 DCBD Use stencil for Dual ColorBurst Display (1) Bit 0 BNK Bank to display 0 = Bank 1; 1 = Bank 2 Note 1: The CoPROcessor will be setup with the correct instruction list for your 24 bit screen when the screen is opened. Note 2: The CoPRO update must be enabled by a call to 'Update_Palette_CoPRO' becuase only the Palette or the CoPROcessor can be updated within a field period (1/60th of a second for NTSC or 1/50th for PAL) You must arbitrate which you would like to update by calling 'Update_Palette_CoPRO' ____________________________________________________________________________ [9] SetLoadAddress Sets the ColorBursts Video address counters with this address when a load instruction is executed by the ColorBurst. This is what is used for vertical and horizontal scrolling and can be implemented for page flipped animation or bring up menus etc at a specified scan line. usage (long) ColorBurst internal video Load Address No return value. ____________________________________________________________________________ [10] Update_Palette_CoPRO Selects whether the Palette or the CoPROcessor will be updated. usage: (byte) 0 = Update Palette, 1 = Update CoPROcessor No return value. Note 1: Only either the palette or the CoPROcessor can be selected for an update per frame (1/60th sec NTSC or 1/50th sec PAL). This function can be used to assure that you do not get glitches while updating a list for the CoPROcessor or Palette. Just enable update to the Palette while you are setting up your CoPROcessor list or enable update to the CoPROcessor while you are changing your palette list. more graceful routines will be provided to accomplish this. ____________________________________________________________________________ [11] Chng_DataLine Changes the address of the bitplane data port for sending the instruction list of the CoPROcessor and palette data to the ColorBurst. usage: (long) New data line bitmap address returns no data. More details will be provided later. Note: This does not need to be modified under 'Normal' circumstances. _____________________________________________________________________________ [12] Chng_NoWrt_DataLine the same in operation as 'Chng_DataLine' but only changes this data port address for the copper lists that are used when no video update is enabled usage: (long) New data line bitmap address No return data. Note: This does not need to be modified under 'Normal' circumstances. _____________________________________________________________________________ [13] Select_Col_CoPRO similar in operation to 'Update_Col_CoPRO' but is a lower level interface and requires use of 'Set_Control_Bit' to give greater control. useage: (byte) 0 = Update ColorPalette , 1 = Update CoPROcessor No return data. ____________________________________________________________________________ [14] Set_Control_Bit Sets or clears a specific bit in a specified Control word. usage: (long) pointer to Control data bitplane memory (byte) status of bit to modify (0 or 1) (byte) bit to modify (0 - 15) No return data. ____________________________________________________________________________ [15] Set_Menu_Position used in the paint program to setup an Amiga 5 bitplane lo-res menu and cut it any at the specified vertical position or disable the menu entirely. useage: (word) Menu Vertical position No return data. ____________________________________________________________________________ [16] Set_DMA_Ratio allows you to control the update speed to ColorBurst for faster screen operations. suggested use of this would be during operations such as area fills. by slowing down the update rate of the ColorBursts display, it gives the Amiga processor much faster access to chip memory becuase the 68000 will have much less DMA conflict. By slowing down the update rate by a ratio of 2 you will be able to get around a 250% increase in screen operations including Blitter and processor operations. Most 24 bit cards are hardwired to full speed DMA use and would not give you the ability to turn its own DMA off to allow faster access with the 68000 without losing its picture. You can entirely turn Amiga DMA off but still fully display the ColorBurst picture if required. No real speed increase is obtained with a DMA ratio of higher value than 2. a value of 1 still gives about half the update rate but faster access. a value of 0 would be used for normal painting opertions and full realtime screen updates. A value of $ff will turn off Amiga DMA totally until it is changed to another value. useage: (byte) The DMA ratio setting No return value. Important Note: The greater the DMA ratio, the slower the update will be to the ColorBurst memory of the changes to the picture. also with higher DMA ratios you will notice definate 'steps' of updating to the screen. You need to select the compromise for your situation. for long sets of pixel updates to the screen I suggest a value of 2. For realtime painting use a value of 0, for loading a picture use a value of $ff to hold your old picture until the new one is loaded, then update the ColorBurst display with the new picture. ____________________________________________________________________________ [17] Load_Menu_Palette Loads the Menu with the 32 colors that you want for your menu. This is used in the paint program menu selector. useage: (long) pointer to your list of palette settings for the Amiga Menu. No return value. Note : You should have your colors in a word format with 4 bits for red, Green and Blue. eg $0RGB starting with palette color 0 and the last word will be color register 32 ____________________________________________________________________________ [18] Set_Menu_BitMap Loads the address of the Menu Bitplanes into the ColorBurst menu Copper list useage: (long) pointer to list of bitplane pointers No return value. bitplane pointers should be 5 longwords staring with bitplane 0 and ending with bitplane 4. Note: The Amiga Menu will not display unless you link your menu bitplane pointers into here after opening the ColorBurst screen. ____________________________________________________________________________ This is a very preliminary set of details on the Library. A full set of documents will cover every aspect of programming ColorBurst at the highest and lowest levels of control. Full developer support and information is available on the MAST BBS at (702) 359 0132. Full kits will be available shortly. All code can be used or be modified for use in any commercial software.