Fresh Fish 5

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

/ Fresh Fish 5 / FreshFish_July-August1994.bin / bbs / dev / cmanual-3.0.lha / CManual-3.0 / Graphics / CopperDraw / CopperDraw.doc < prev next >

Wrap

Text File | 1993-10-12 | 20.9 KB | 616 lines

/***********************************************************/ /* */ /* Amiga C Encyclopedia (ACE) V3.0 Amiga C Club (ACC) */ /* ------------------------------- ------------------ */ /* */ /* Book: ACM Graphics Amiga C Club */ /* Chapter: Copper Tulevagen 22 */ /* File: CopperDraw.doc 181 41 LIDINGO */ /* Author: Anders Bjerin SWEDEN */ /* Date: 92-05-01 */ /* Version: 1.00 */ /* */ /* Copyright 1992, Anders Bjerin - Amiga C Club (ACC) */ /* */ /* Registered members may use this program freely in their */ /* own commercial/noncommercial programs/articles. */ /* */ /***********************************************************/ I N S T R U C T I O N S ----------------------- 1.0 INTRODUCTION Copper Draw is an extremely useful utility when you want to create Copper lists. You have at all time full control over what you are doing and you will immediately see how your copper list changes as you modify it. Copper Draw was written to be as easy as possible to use, and is fully amigaized. It can create copper lists for all colour registers, and when you quit the program will automatically save the copper list in C code that can be included with your programs. CopperDraw is using linked lists and can therefore handle as many copper instructions as you want. All memory and other resources are (of course) returned when the program terminates, and the program follows all "rules". This program is a part of the "Amiga C Encyclopedia", the largest C collection of information, programs, examples, and utilities for the Amiga. I have spent more than four years on writing and improving these manuals, and with your help I can continue to make then even better. Please register! 2.0 HOW TO START COPPERDRAW CopperDraw can either be run from the CLI or Workbench. If it is started from CLI you can specify the name of the file where the source code for the copper instructions will be saved. You can also give the copper pointer a name, set the screen height (values between 95 and 256 are accepted) and the number of bitplanes that should be used (1 bitplane = 2 colours, 2 bitplanes = 4 colours and so on, up to 5 bitplanes = 32 colours). If CopperDraw is started from Workbench or you have given the program illegal parameters, the default values will be used. The default file name is "RAM:Copper.c", pointer name is "copper", screen height is set to 200, and five bitplanes are used (32 colours). To start from CLI you write: CopperDraw <output> <copper name> <number of bitplanes> <screen height> To start CopperDraw with 8 colours (3 bitplanes), 256 pixels tall display and use the file name "MyFirstCopperList.c", you would write: To start CopperDraw from Workbench simply double click on the CopperDraw icon. The default values will be used. 3. USE COPPERDRAW When you start CopperDraw the whole screen will be filled with one large screen. On top of the screen one window is opened. The window should look something like this: Quit | | Red, Green and Blue sliders | | +-|-+--|--------------------------------+ | v | | | +---+--|--------------------------------+ | +--|-----------+ +-+ | | R |# | | |0| COLOUR <----- Current edit mode | +--|-----------+ +-+ +------+ +--+ | | G |# v | |0| |SPREAD| |EX| | | +--------------+ +-+ +----+-+-+--+<-- Gadgets | B |# | |0| |COPY| |UNDO| | | +--------------+ +-+ +----+ +----+ | | +-+-+-+-+-+-+-+-+ +---+ +------+ | | | | | | | | | | | |ADD| |DELETE|<-- Special Copper | +-+-+-+-+-+-+-+-+ +---+ +------+ | gadgets | ^ | +--------|------------------------------+ | Colour registers As you notice it looks rather similar to normal "Colour Requesters", but this one is much more powerful and fun to use. 3.1 THE NORMAL COLOURS One of the advantages with CopperDraw is that you can both create copper lists and edit the colours as normal. To use it as a normal colour requester does not differ much from other colour requesters. If you look at the window just above the gadgets you will see the text "COLOUR". As long as this text is there the program will work as any other colour requester. If you start to edit the copper list the text will be changed, and you will see the word "COPPER". When you are editing the copper list the requester will work differently as will be described in the next section. 3.1.1 SELECT COLOUR When you start CopperDraw you can set the number of colour registers that should be used. The available colour registers will be listed below the colour sliders. Each colour register is represented with filled box. The more bitplanes you are using the more available colour registers: Bitplanes Colour Registers ---------------------------- 1 2 2 4 3 8 4 16 5 32 To select one of the colour registers simply move the mouse pointer to one of the boxes and press the left mouse button. The colour will be selected (a small box is drawn around it), and the colour sliders are automatically adjusted. 3.1.2 CHANGE COLOUR Once you have selected a colour register you can start to alter its colour. By moving the buttons inside the colour sliders the colour is automatically changed. The further to the right the buttons are moved the brighter colour. The first slider adjusts the red intensity, the second slider the green intensity and the third slider the blue intensity. 3.1.3 COPY COLOUR To copy the current colour to another register click on the "Copy" gadget. The mouse pointer should now contain the text "to". Now move the pointer to the colour register you want to copy the colour to, and click once on the left button. The colour is copied, and this colour register will be selected. 3.1.4 EXCHANGE COLOURS To exchange the colours from one colour register with another colour register click on the "Ex" gadget. Move the mouse pointer to the colour register you want to change colour with, and press the left mouse button. The colours are exchanged, and this colour register will be selected. 3.1.5 SPREAD One nice feature is that you can spread a colour from one colour register to another colour register. The colour registers between will be changed so the colour is smoothly altered from the first colour register to the second colour register. This is very useful when you want to create shadows etc. 3.1.6 UNDO We are all humans (well, most of us at least) and we do make mistakes. Luckily you do not have to worry about this since you can always press the "Undo" gadget, and the colours will be restored to the values they had before the last operation. 3.2 COPPER INSTRUCTIONS Now the magic begins! There exist a special coprocessor inside Amiga computers that is called "Copper". The great thing with this processor is that it can alter the colour values of the colour registers as the display is drawn. One colour register can therefore display several colours. What you have to do is to tell the Copper where on the display the colour value should be changed, and to what colour. In C you would use the CWAIT() and CMOVE() macros. Since the Copper is a coprocessor it will not slow down the main processor. You can use hundreds of different colours but still only use very few colour registers. Normally is only the background colour (colour register 0) altered by the copper, but you can of course alter any colour registers you want. CopperDraw can alter all colour registers. 3.2.1 ADD COPPER INSTRUCTION If you want that the Copper should alter a colour, you have to add a copper instruction. To add an instruction press the "Add" gadget. The mouse pointer will change image, and the text "COLOUR" will be replaced with the text "COPPER". Move the mouse pointer outside the window to the (vertical) location where the colour should be changed, and press the left mouse button. A special pointer in the left margin will appear telling you where the instruction was placed. If you now start to move the buttons inside the colour sliders you will notice that you are changing the colour below the line you place the copper instruction. You can place as many copper instructions as you want! 3.2.2 SELECT COPPER INSTRUCTION If you want to change a copper colour you have previously set, you simply move the mouse pointer to the line you want to change and press the left mouse button. You will notice that the left pointer is moved to the new location, and the colour sliders are automatically adjusted appropriately. You can now alter the colour. You do actually not need to point exactly on the line to select a copper colour. CopperDraw will select the first copper colour which is above the mouse pointer. To select a colour you simply point on the correct line or any line below it until the next copper colour. You can always look at the small copper cursor in the left margin to see which copper colour (line/instruction) is currently selected. If you can not see the copper cursor, no line is selected. 3.2.3 DELETE COPPER INSTRUCTION To delete a copper colour you press the "Delete" gadget and move the mouse pointer to the copper colour (line/instruction) you want to delete. Press the left mouse button to remove the it. (The first copper instruction/colour just above the mouse pointer will be removed.) 3.2.4 COPY COPPER INSTRUCTION If one of the copper colours is selected you can copy it to another (previously set) copper colour. Press on the "Copy" gadget and move the mouse pointer to the copper colour you want the current colour to be copied to, and press the left mouse button. The colour will be copied, and the destination copper colour will be selected. Note that the text "COPPER" must be on. If it says "COLOUR" you have not selected a copper instructions, which you must do first. 3.2.5 EXCHANGE COPPER INSTRUCTIONS To exchange one copper colour with another you press on the "Ex" gadget, move the mouse pointer to the destination copper colour, and click on the left mouse button. The copper colours will be exchanged, and the destination colour will be selected. 3.2.6 SPREAD This is probably the most useful feature with CopperDraw. Select a copper instruction, press the "Spread" gadget, and finally select a destination copper colour. CopperDraw will now automatically generate as many new copper instructions as necessary to make a smooth transition between the two colours. With this function you can within seconds create smooth coloured skies and spectacular colour compositions! Let me demonstrate this with an example. Add a copper colour at the bottom of the screen. Change the colour to black. Add another copper colour somewhere on the middle of the screen. Change it to bright red. Click on the "Spread" gadget and move the mouse pointer to the bottom of the screen, and press the left mouse button. CopperDraw will immediately create 14 new copper instructions and set the colours so you get a smooth transition from the red colour to the black! 3.3 SWITCH BETWEEN COLOUR REGISTERS Although the background colour (colour register 0) is often only used, you can alter any of the colour registers. If you want to alter the colours of another colour register you simply move the mouse to one of the coloured boxes and click on the left mouse button. CopperDraw will now automatically fill the whole display (except the border were only the background colour can be used) with the selected colour. If you now add copper instructions you will affect the colours of the selected colour register. You can use up to 32 different colour registers (5 bitplanes), and each colour register can have its own copper colours! 3.3.1 DISPLAY ALL COLOUR REGISTERS It can sometimes be necessary to see all colour registers at the same time. If you press key "F9", CopperDraw will fill the screen with a rectangle for each colour register. You can now as before add and alter the copper colours. Note that you will only alter the selected colour register, and if you want to alter another colour register you have to select it first. The copper cursor which previously always was located on the left margin will now move horizontally to the current colour register and vertically to the current copper instruction. 3.3.1 DISPLAY CURRENT COLOUR REGISTER To remove the rectangles and use the current colour register as before, press "F10". 3.4 REMOVE THE WINDOW If you want to see the while display without being disturbed by the window you can press on the "delete" key ("Del" is placed on the left side of the "Help" key). The window will immediately disappear. If you press on any key the window will become visible again. 3.5 QUIT Once you have created your copper list you should quit. Press on the close window gadget (top left corder of the window), and the program will save the current copper list in C code, and then terminates. The copper file can then easily be included in your own programs, and you will then almost directly have a Mega Demo! (Well at least a nice copper list.) 4.0 IMPORT THE COPPER CODE IN YOUR OWN PROGRAMS Once you have created a nice copper list you quit and the list will automatically be converted to C code and saved. This code can then easily be included in your own programs. 4.1 COPPER FILE A short copper list for a two coloured screen with only four copper colours would look something like this: /***************************************/ /* */ /* Copper List made by CopperDraw V1.0 */ /* Amiga C Encyclopedia, Anders Bjerin */ /* */ /***************************************/ /* The copper list: */ CINIT( copper, 1 ); CWAIT( copper, 62, 0 ); CMOVE( copper, custom.color[0], 0x0F00 ); CWAIT( copper, 134, 0 ); CMOVE( copper, custom.color[0], 0x00F0 ); CMOVE( copper, custom.color[1], 0x000F ); CWAIT( copper, 182, 0 ); CMOVE( copper, custom.color[0], 0x0FF0 ); CEND( copper ); /* The Colour Table: */ UWORD my_color_table[]= { 0x666, /* Colour 0 */ 0xFFF /* Colour 1 */ }; As you can see will CopperDraw both create a copper list and a colour table. Note that line 134 there exist two copper colours. Both colour register 0 and 1 are altered, but since they are on the same line only one CWAIT() call is done. 4.2 HOW TO USE THE COPPER LIST To use a copper list you only have to follow these steps: 1. Declare a Custom structure called "custom". This structure will automatically be initialized by the Amiga. Note that on most compilers it has to be declared together with a "far" statement. (The Custom structure is usually placed far away from you code, and to reach it you have to use "far" pointers. extern struct Custom far custom; 2. Declare a pointer to a copper list structure. It should have the same name as the "copper name" argument you used when you started CopperDraw. The default name is "copper", and should be used if you did not give it some other name. struct UCopList *copper; 3. Allocate some chip memory for a UCopList structure. If it is not chip memory the Copper can not reach it, and your copper list will not work. The memory should also be made "public" so other parts of the Amiga may use it. This structure will later be connected to a ViewPort, and the ViewPort will automatically deallocated the UCopList structure when you close the ViewPort. We should therefore not deallocate it ourself as might be expected. Remember to always check if you received the memory! copper = (struct UCopList *) AllocMem( sizeof(struct UCopList), MEMF_PUBLIC|MEMF_CHIP|MEMF_CLEAR ); if( !copper ) clean_up( "Not enough memory!" ); 4. You should now open your own screen or create your own display. See chapter "LowLevelGraphics" for more information about displays. 5. After the display has been prepared you execute the copper list. Remember that you must always start with a CINIT() call, and finish off with a CEND() call. CINIT( copper, 1 ); CWAIT( copper, 62, 0 ); CMOVE( copper, custom.color[0], 0x0F00 ); /* ... */ CEND( copper ); 6. You should now link the UCopList memory to the ViewPort. If you have created your own display you already have a ViewPort structure. If on the other hand is using a screen under Intuition, you can find the ViewPort structure in the "ViewPort" field of the Screen structure. my_view_port = &(my_screen->ViewPort); Once you have the address to the view port you give the UCopIns field of it the address to your own copper list. ("my_view_port" is a ViewPort structure.) my_view_port.UCopIns = copper; 7. You can now tell the Amiga to generate its own copper list with help of yours. You do it by calling the MakeVPort() function. This ViewPort's copper list should then be merged together with the others ViewPort's copper list by calling the MrgCop() function. Finally you call the LoadView() function to let the user see your new display and copper list. ("my_view" is a View structure) MakeVPort( &my_view, &my_view_port ); MrgCop( &my_view ); LoadView( &my_view ); If you have opened a Screen under Intuition you should not use low level functions like MrgCop(). Instead you should call the RethinkDisplay() function which will automatically create the display for you. RethinkDisplay(); 8. If you have created the display yourself you should call the FreeVPortCopLists() and FreeCprList() functions when you want to close the display. They will automatically remove and deallocate all copper lists for you. FreeVPortCopLists( &my_view_port ); FreeCprList( my_view.LOFCprList ); If you have opened a screen under Intuition this will be done automatically when you close the screen. 4.3 EXAMPLE See the examples in the "Copper" chapter. 5.0 BASIC, ASSEMBLER AND PASCAL PROGRAMMERS The code generated by CopperDraw can easily be included in your own C programs, but can also easily be included in your own Basic, Assembler or Pascal programs too. You may have to rename some of the macros, but it should not be difficult. Please note that I am a C programmer and can hardly add 1 + 1 in Assembler, and is not familiar with Basic nor Pascal on the Amiga. I can therefore not help you with any questions you might have about how to create copper lists. Try to find some friends or a user group that can help you. To all Amiga Programmers, have FUN!!! NOTE! This is a non registered version, and no copper list file will therefore be created! To get the complete version simply register your copy. The registration fee is only £30, $60, SEK 300, or similar amount in your own currency (price includes everything). The Amiga C Encyclopedia is the largest collection of documents, examples and utilities in C for the Amiga and it is still among the cheapest manuals. But this is not all, a registered owner will also get: 1. Two disks containing the last parts of the encyclopedia. The disks will be sent by first class air mail. 2. Registration card for the Amiga C Club (ACC). 3. Immediate information about updates. 4. Updated versions of the encyclopedia for only the cost of disks plus postage and packing. 5. Assistance with digitizing colour pictures and sampling sound effects. 6. Unlimited help with your C programs. You never have to be alone with your problems. 7. The right to use parts of the manual in your own commercial/non-commercial programs/articles. Can any other manual give you all this??? The simplest way of paying is to include the money in a letter in cash. US dollar bills, English pounds or Swedish SEK are preferred, but all currencies are accepted. You can also send the money as a "Postal Money Order", ask your local bank or post office. Please do not use cheques. It is sadly extremely expensive to cash a foreign cheque here in Sweden. If you live in Scandinavia you can send the money to "Svenska Post Girot, postgiro konto: 641 88 30 - 3, betalnings- mottagare: Datra". Please send the registration fee together with your complete address to: Datra, Amiga C Club Anders Bjeri Tulevagen 22 181 41 LIDINGO SWEDEN I have worked for more than four years now with this encyclopedia, and with your help I can continue to improve it. Happy programming!!!