@database amigaguide.datatype @wordwrap @node MAIN "BlackBoard Documents" @{u}ABOUT THIS DOCUMENT@{uu} This document is organized so that the farther you go through it the less general the information becomes. Try to read through the first few sections at least before you rush in, get frustrated, and have to come back and read it anyway. These bits deal with setting up, and general use. The further on bits in the document are more reference-like for when you want to use a particular function. Choose from ... i) @{" Introduction " LINK INTRO} ii) @{" Basic Options " LINK BASIC} iii) @{" Modules " LINK MODULES} iv) @{"Programing Info" LINK PROG} ---------------------------------- Dedicated to Lizzy - love from all your friends @endnode @node INTRO "Introduction to the Program" @{u}INTRODUCTION@{uu} BlackBoard is an image proccessor written specifically for the AGA chip-set machines. The system requirements are 2 floppy drives (or a hard drive), and at least a meg of memory. Ideally you should also have a bit more memory and the AGA chip-set. The program is formed by a number of disk-based modules which are run as required. This means that almost every aspect of the program can be upgraded and improved without having to re-write the whole thing. It also means that anyone can write their own add-on modules (e.g. Loaders, Displayers, filters etc.) providing they stick to certain guidelines. @{u}SETTING UP@{uu} The first time you run BlackBoard you must select the type of chip set you have. If you have any machine with the AGA chip set (e.g. A1200,A4000 or A5000) then run the file entitled '24bit_Amigas'. Otherwise run the program called '12bit_Amiga'. Each time, before you run the program, the program INIT must be executed. This can be done either through a startup-sequence or you can just double-click on it's icon. This sets up a number of system variables. When you run it it may ask you to insert 'BBoard:'. This is simply checking if the 'volume' already exists. Simply click on CANCEL and the program will assign it to the RAM disk. You can then run the main program - BLACKBOARD @{u}RUNNING IT@{uu} While using the program you must keep the disk 'BlackBoard:' in the drive at all times. This is because it contains all the functions and filters and stuff which you can use. If you take it out the program can't find what it wants (say the program which displays the picture) and so can't do what you want. If you want to access the programs which are placed on the second disk then there are a number of ways that you can do this. @{"More info" LINK DISK2} The file called 'BlackBoard:BBprefs' contains what files can be accessed from the main program, and how to do it. If a program appears on a button on the program, it doesn't mean that it is available at that time, just that if you press it, BlackBoard will TRY to run it. If it's not on the main disk you can only run from the 'Sub Progs' button. @{"More info" LINK PREF} @endnode @node BASIC "Basic User Information" @{u}BASIC STUFF@{uu} Along the top of the window you will see a number of buttons. With 2,4,8,16 etc. on them. These control how the pictures will be displayed. These select the amount of colours you want the picture to be rendered in. These range from 2 to 256. Three other modes are available, HAM, HAM8 and EHB. HAM and HAM8 allow 4096 or 256,000 colours to appear on screen simultaneously, whereas EHB allows 64 colours to be used - although only half can be defined independently. 'But why don't you use the 64 colour button?' I hear you cry. Well machines before the A1200 (the 12bit_Machines) can only use 2,4,8,16,32,HAM and EHB modes. So even if you've get an AGA machine you may want any output produced to work on these earlier machines. Next are three button, 'Dither', 'HiRes' and 'Lace'. The first controls whether or not the program uses dithering routines when it renders the picture. See the 'Chnge Dither' button for more information. The other two buttons simply control how the screen is displayed. N.B. On the older machines ('12_Bit') you can only have HiRes in 2,4,8 or 16 colours. @{u}THE MAIN BUTTONS@{uu} Beneath and to the right are the main features, which are listed below... @{u}Load@{uu} This will load in from disk a new picture, using the default loading module (normally IFF - the same file as 'Deluxe Paint' and 'Photon Paint' use). See below for changing the format. @{u}Save@{uu} This will save to disk the currant picture, using the selected routines for displaying and saving. @{u}Picture Info@{uu} This will tell you about the picture and the currently selected options. @{u}Chnge Dither@{uu} This button allows you to change the way in which (if requested) the program will dither a picture. Fundamentally there are two types supported, either mapping or Floyd (error distribution). If you select the 'Floyd' method NONE of the other options apply. If you choose mapping, you have to choose a mapping style (three are supplied, with some more on the second disk) and an intensity. This intensity controls how much the mapping pattern is applied to the picture, the higher the function the more dithering. A value will be suggested for the currant amount of colours. This value is ignored if the picture is grey-scale. @{u}RGB Control@{uu} Basic at the moment. Colour images can be separated by a number of different methods one way (and the only way that the program supports at the moment) is to split it up into red, green and blue components. This function allows you choose each bit and change it independently. @{u}Palette@{uu} Generates the 'best' colours for the currant data. This is NOT run separately when you alter the picture. If you change the pictures colours (except using the sliders at the bottom of the display, or the edit mapping routine) you may need to run this. @{u}Display@{uu} Displays the picture using the currant display options. @{u}Preview@{uu} - As above but can use faster (and less accurate) routines. @{u}Sub Prog@{uu} Allows you to run a module or sub-prog which doesn't appear on the gadgets. Just select the name of it, and click on RUN. With this you can run programs not on the main disk. @{u}Quit@{uu} Quits the program. If you ask for the data to be deleted you will have to run INIT before re-loading BlackBoard. However if you don't you can simply re-load with all the data still present. Beneath these system gadgets are 5 sliders. These control the contrast, brightness, red, green and blue contents of the picture. They don't effect the picture directly; the displaying routines calculate effects as they draw it up - and therefore there is no need to re-calculate the palette if they are changed (or indeed if the number of colours selected is altered). To the left are the filters and effect which can be run from the program. The important ones have a button to themselves, and the rest are present in the box. They can be scrolled up and down with the correct buttons, and run by clicking on the 'RUN' button. They are all listed below, and what they do. But first... How you enter info to them? @{u}DATA ENTRY@{uu} Each subprog can ask for a number of different types of data. The main program will gather these and then pass them on to it. In this way writing your own modules is much easier as you don't have to worry about the front end. Anyway, any information which is requested BY the subprog will be asked for by a set of buttons which appear in the middle of the screen. These will be of a number of sorts, all of which should be easy enough to work out (I hope). @{u}THE SYSTEM ROUTINES@{uu} If you want to change any of the system routines simply go up to the pull-down menu at the top of the screen and select the one you wish to change, and the select the one you want from the choice listed. Each program does the same thing (e.g. They all calculate the palette, or they all load an image) but they do it in a different way. (e.g. Different loaders may load pictures which are saved in different formats) @endnode @node MODULES "Modules Menu" @{u}Disk 1@{uu} Choose from ... @{"Loader modules" LINK LOAD} @{"Saving modules" LINK SAVE} @{" Displayers " LINK DIS} @{" Proccessers " LINK PRO} @{"Morph" LINK MORPH} or @{"Warp" LINK WARP} @{"Edit(NON-AGA) " LINK EDIT} @{u}Disk 2@{uu} Choose from ... @{" Using Disk 2 " LINK DISK2} @{"Loader modules" LINK LOAD2} @{" Displayers " LINK DIS2} @{" Proccessers " LINK PRO2} @{" Edit(AGA) " LINK EDIT} @{" Textures " LINK TEXT} @endnode @node DISK2 "Using the progs on disk 2" Not all the functions which are currently written for BlackBoard can be fitted on a standard AmigaDOS floppy drive. For this reason some of them (the ones which I consider to be less use) have been put on here. These include less useful functions (e.g. 'Inverse') and function which will only work on the new AGA machines (e.g. Preview18) There are three ways to access these new functions. i) Using the 'Sub Prog' button on BlackBoard. If you click this and then swap disks and choose one of the other functions, (found in the ':Subprogs/' directory) then you can run it. ii) By swapping files between the two disks. If there is a file on the main disk which you don't use, swap it over for the feature you do use. iii) The best option by far is to put everything on a hard drive. If you have the money to buy a hard drive I can't recommend it enough. It provides such an increase in ease of use that you can't imagine how to live without it after you used it for a bit. Anyway. All you have to do is create a directory on your hard disk (e.g. 'DH0:BlackBoard') and in it put all the files (from both disks) in it (In their own sub directories; e.g In'DH0:BlackBoard/Subprogs/Loaders' for Load_ILBM). You must also ASSIGN it the proper name of 'BlackBoard:' so put the following in your 'startup-sequence'... ASSIGN BlackBoard: DH0:Your Directory @endnode @node LOAD2 "Loading routines (On Disk 2)" @{u}Load_Arc_Sprite@{uu} This module is also a 'loader', but this time it will load in pictures saved in the standard file format on the Archimedes computer. @endnode @node DIS2 "Palette and Display routines" @{u}Palette routines@{uu} @{u}Palette18@{uu} As Palette 12 but a bit slower. The colours chosen are also accurate to 18 bits (265,000 colours). @{u}Displayers@{uu} For general info see the Disk1's page (@{"Jump to it" LINK DIS}) Routine Accuracy Dither Speed Other info. ------------------------------------------------------------- Display12 12 bits Not Floyd Medium Low memory version Display24 24 bits YES Slow High quality output Preview18 18 bits NO Fast For AGA machines Grey_HAM 18 bits NO Medium See below PreviewThres 4 bits NO Fast Fastest previewer Grey_HAM, is a grey-scale displayer will by using different colours, appear to display 128 grey-scales on a non-AGA machine. (You must turn your VDU's colour control to zero) @endnode @node PRO2 "Image Processing Tools" @{u}Reduce_Noise@{uu} Provides two routines to 'smooth' and reduce noise in the picture. @{u}Flip@{uu} Flips the screen in either the x or y direction. @{u}Pixelate@{uu} This will turn the picture into a number of coloured blocks. The size of these blocks can be selected in both the x and y dimensions. @{u}Quantise@{uu} Each pixels RED, GREEN or BLUE (or GREY in 8-bit mode) is controlled by a number from 0 to 255. 256 shades is as many shades as the human eye can distinguish - but with this function you can change the amount of shades that lie between the two extremes. The program will want a number between 1 and 8. This 'bits' value controls how many shades the picture is converted to. In essence.. A bit value of 1 -> 2 shades A bit value of 2 -> 4 shades 3 -> 8 shades 4 -> 16 shades 5 -> 32 shades 6 -> 64 shades 7 -> 128 shades A bit value of 8 -> 256 shades (No change) @{u}Arc_Palette@{uu} The Archimedes computer (at least the lower range ones) have very simple control over the colours that you can have in a picture. This program will select the colours used on the Arc so that any pictures that you display (256 colours) can be ported directly over to the Archimedes. @endnode @node LOAD "Loading routines" @{u}Load_ILBM@{uu} This is the default. Will load in IFF (ILBM) pictures. Up to 16 million colours. @{u}Load_Sculpt_File@{uu} Sculpt files are uncompactable, contain no structure (width, height etc.) information and are saved (if in colour) as three different files. Most filters which load in files will however expect them to be in sculpt format.. Why? Because it's easy to read, easy to calculate where specific pixels will be in the files and requires no computation to convert into 8 or 24 bit files. They therefore are easy, quick and memory (RAM not disk) efficient. Because they have no picture information you must type in the width of the file and if it is colour (three files .red, .gre and .blu) or greyscale (just the one). This is done so you can load in say a .red file as a grey-scale and manipulate it separately. @{u}Screen@{uu} This 'loader' will instead of loading a picture from disk, 'grab' it from one of the screens currently being used on the system. (e.g If you have DPaint loaded, you can grab the screen directly from the computers memory, instead of having to save it out and then reload it) @endnode @node SAVE "Saving routines" @{u}Save_ILBM@{uu} Saves out current screen (colours, palette, width etc.) as an IFF file, which can be loaded into almost every Amiga art package. @{u}Save_Sculpt_File@{uu} This saves the picture as a sculpt file. Data about the picture is NOT saved, and the width is required when you reload. So it's best to save the picture as something like "MyPicture(320)" where the '320' is the width. Colour images will be saved as 3 files, each one with a suffix. i.e. Filename.red, Filename.gre and Filename.blu. @endnode @node DIS "Palette and Display routines" @{u}Palette routines@{uu} @{u}Palette12@{uu} This calculates the colours, but only to a resolution of 12 bits (4096 colours). @{u}Displayers@{uu} Firstly there are two types of displayers;- grey-scale ones and colour ones. Only one proper grey-scale one is provided, so you don't have a lot of choice there - but this does everything anyway so it doesn't matter. Of the colour ones there is 1 on this disk (2 on Disk 2) There is also one previewer on this disk (and two on disk 2) Routine Accuracy Dither Speed Other info. ------------------------------------------------------- Display15 15 bits YES Medium Preview12 12 bits NO Fast Low memory needs GreyDisplay 24 bits YES Fast The previewer's (Preview12/Preview18/PreviewThres) will display all pictures (ignoring the number of selected colours) in HAM/HAM8,16/256 grey-scale mode using a fast routine. Very useful throughout the development to see how the pictures going. @endnode @node PRO "Image Processing Tools" @{u}Double_Or_Half@{uu} These double or half the picture. They don't just double the pixels, but work on the image to prevent a 'blocky' look. If you WANT a 'blocky' look use SCALE. @{u}Edge_Enhancer@{uu} Will either outline of enhance a picture. If you choose to enhance the picture then the value entered affects how pronounced this enhancement is. 0 will produce the most amount of edge enhancement, the bigger the number the less noticeable the effect. @{u}Emboss_Image@{uu} Creates the impression that the image is three dimensional. @{u}Composite_Load@{uu} This will load in another picture (Sculpt format) and merge it into the picture presently in memory. To do this it needs three pieces of information. Firstly the filename and it's size. Secondly it needs the percent of which to merge (0-100%). If this is 100% the new picture will totally replace the old one; if it's 50% they will mix 50-50. Thirdly it needs a threshold value. This value tells the computer what bits of the image to merge, and what to make 'see-through'. If the pixels' value is beneath the threshold then the new image is deemed to be 'see-through' e.g. The value can be between 0 and 255. If you enter 1 - Everything on the new image will used, except when it's colour is black, then it will be transparent. Finally position the new image on the old one and click on 'OK'. N.B. Colour images can't be mixed with grey-scale pictures and vice-versa. @{u}Shade@{uu} This also requires a sculpt picture (this time it must be grey-scale); but instead of mixing the file into the present one, its used to control the intensity of the present image. If the file loaded contains a pixel of 128 (middle grey), then the pixel this maps onto remains the same, if it gets lower, it darkens the pixel, and higher it brightens it. You don't need to place the image on the page because it will be used in a mosaic-like way to effect the entire picture. This function can be used for two reasons. Firstly it can be used to highlight an area (e.g. Fade the picture to darkness as it reaches the edge of the screen) - or it can be used to 'texture' pictures. I've included a number of 'textures' on disk 2 to have a go with. @{"More info" LINK TEXT} @{u}Colour<-->Grey@{uu} Converts a 24 bit (colour) image into and 8 bit (grey-scale) image. And vice-versa. @{u}Crop_Image@{uu} This allows you to cut out a segment of a picture and work with that. If you select 'Auto crop' then you the computer will remove any black area around the picture. @{u}Scale_Image@{uu} Simply change either the actual length or the factors, and then click on 'Scale' to change the size of the image. @{u}Mapping@{uu} Here you can either set the map, or alter it. Setting the map involves permanently altering the picture data in so that it's actually stored in the similar way to how its displayed (i.e. Brightness, contrast, mapping, red, green, blue etc.). Altering the mapping. The images are stored as values from 0-255. Where 0=black, and 255=max red/green/blue/white. You can change this relationship. The graph displayed shows the distribution of colours. Fashion the graph anyway you want, and then click at the bottom. 'Default' will return your mapping to the simply linear relationship. You can also 'bend' the graph up and down by using the appropriate buttons. @{u}Edit_Palette@{uu} The palette created by the palette selector can here be modified. @{u}Rectangle@{uu} Allows you to colour in rectangular areas of the picture. @{u}Change_Range@{uu} The pictures are stored as a block of data, with each red, green, blue or grey point being stored as a number between 0 and 255. This program will show you the min and the max values found in all the data and allow you to scale it accordingly. @{u}Squeeze@{uu} This allows you to squeeze the picture into any four sided shape that you want. Simply move the corner's on the box to select the new shape. You can use it simply of alter the pictures shape, add perspective, rotate, etc. @{u}Bulge@{uu} With this you can 'bulge' or 'pinch' areas of the picture. Select the area you want to effect, and the amount to do it (0= Very little 10=Lots and lots) and set it going. @{u}Clipboard@{uu} This process will DELETE THE CURRENT PICTURE and allow you to replace it with a blank/coloured background onto which you can 'Composite_Load' files onto, texture ('Shade') or edit using EDIT. @endnode @node EDIT "The Edit function" @{u}EDIT@{uu} This is NOT an art package, and therefore I've not called it all the pretentious names which seem to go with these 'packages', such as 'Deluxe', and 'Brilliance' etc. No, this program is called 'Naff-Paint'. What Naff-Paint does it does well, and reasonably fast considering it's working in 24-bit graphics - It simply doesn't do much. Its written to be an editor to allow you to edit, and tidy up pictures. It's not designed to enable you to draw them from scratch. I will be adding more functions and improving it as I go, and new versions will appear on the P.D. updates. There are two versions. The two , 'Edit(NON-AGA)' and 'Edit(AGA)' (Found on the second disk) are identical except one will only work on AGA machines, and displays four times the amount of pixels at one time. The other will work on non-AGA machines - and is also faster as it only works in 4096 (or 16 shades). Both versions work on the picture in 16 million colours all that changes is how it's displayed. AGA owners should consider using both because of the speed advantage which he standard version has. When first run, click in the picture box to select an area to edit. This will then be displayed on the screen, using large pixels. The gadgets you can use are as follows. @{u}Sliders@{uu} The 4 sliders at the bottom of the screen control either the colour that you are using (with colour pictures) or the intensity which is used with grey-scale (8-bit) pictures. @{u}Top-Buttons@{uu} These 4 buttons contain the function that will be performed on the picture... i) Absolute - Just like painting onto the picture. ii) Smooth - This will smooth the pixels, irrespective of what colour/intensity you have selected. iii) Blend - With this you can mix the colour you've got with whatever is already on the screen. iv) Colourise - In colour mode (24-bit) this will colour the pixels under the brush with the selected colour, but still keep how bright/dark they are. @{u}Brush Options@{uu} Beneath these are three gadgets. One controls the size of the brush, from 1 to 9 pixels wide/high. The other two control the shape of the brush, either a square or circle. @{u}Moving Buttons@{uu} There are three ways to move the screen. One is to click around the edge of the picture (off the picture but within the box), another is to use the Position button (see below) this is this third. With the UP,DOWN,LEFT and RIGHT buttons you can move the screen 40 pixels (a whole display) whatever way you want. @{u}Options@{uu} These 6 buttons perform a function.... 'Position' - Brings up the screen at the start, and allows you to re-select a new area. 'Preview' - Using the currant display options (see main manual) and the default previewing function, this will show the SAVED complete picture. (Therefore 'save' it before you run this option) 'Pick' - After clicking this, click on the picture and the colour under the pointer will be transferred to the sliders. '(Re)-Load' - This will re-load in the data, and so revert to the picture the last time it was saved. 'Save' - This saves the data back to the 'BBoard:' device. 'Exit' - This returns to the main program. IF YOU HAVE NOT SAVED IT THEN THE CHANGES YOU HAVE MADE WILL BE LOST. @endnode @node MORPH "The Morphing function" @{u}Morphing@{uu} This program allows you to 'morph' one picture into another gradually. When first run you must select the detail that the grid is made up of. The more 'boxes' the better the Morph COULD be, but the more effort you have to put in. In the third box the computer wants the picture the one in memory is to be morphed into (It must be the same size, saved in sculpt format and the same as the one in memory (e.g Greyscale or Colour) After this the program will draw up the two pictures, and show the morphing grids. It will then display, in turn, the two preference boxes. The first one contains the main options. @{u}Main Prefs@{uu} * The program will save out the animation frames in SCULPT format. With this option on you can then convert these to the standard IFF format. * This next option contains the filename for the animation. e.g. If the filename is 'DF0:Animation' then the first frame would be 'DF0:Animation1', plus '.red','.blu','.gre' or '.IFF' * The next option allows you to change the amount of frames between the two pictures. You must have at least 2 frames. * The 'Handle' option allows you to alter the size of circle at each 'node' of the grid. Try value '0' or '5' if it's hard to see the grid. The next menu only comes up if you want the frames converted to IFF format, as it controls how these are produced. @{u}IFF Prefs@{uu} * The Display routine is the same one as used by the main program. * The Palette program is used to select the colours for the IFF pictures. The display mode (e.g. HAM, 16 colour, HiRes) can only be selected from the main runner program. * If you select 'Delete Sculpt', then the sculpt files are deleted after IFF file has been created from it. * If you select 'Lock Palette' then one palette is selected for all the frames (Greyscale pictures don't need palettes). Otherwise the program will select the best colours for each frame in turn. After you've done this you can edit the morphing grid to your requirements. Try to make the equivalent box on both pictures bound the two area you want morphed together (e.g The eye, or mouth). When you're done click on MORPH and the frames will calculated and if selected then they will be converted (in reverse order) @endnode @node WARP "The Warp function" @{u}Warping Pictures@{uu} This function is very similar to the MORPH function. It allows you to 'drag' any the boxes' corners about, and in doing so 'warp' the picture into that new shape. Try it out and see what I mean. @endnode @node "TEXT" "Other Programs" These files are SCULPT grey-scale pictures each showing a different texture. There size is in brackets after there name (e.g. 'Beaten' is 80 pixels wide), and by using them with the 'Shade' function you can texture pictures. (e.g. By using 'Weavework' you can make it look like it's printed on canvas) They're found on disk 2 in the 'Textures' directory. Beaten(80) CircleHiLite(160) Circles(23) Diamond(17) Pitted(160) Random(80) Ripple(160) Rock(160) SmoothRock(160) WeaveWork(80) @endnode @node PROG "Programers Information" This bit contains the information which will allow the user to customize the program to his/her own needs. Choose from ... @{"Preferences" LINK PREF} @{"Disk Layout" LINK DISK} @{"New Modules" LINK WRIT} @endnode @node PREF "The Preference file" When the program is run, it will look for a file called 'BlackBoard:BBprefs'. This file is a script file which contains the following information... (each entry is a string terminated with a CR) { Default Loader Default Saver Default Palette routine Default colour display routine Default grey-scale display routine Default colour preview routine Default grey-scale preview routine 1 - Subprog to be placed on the first button 2 - Subprog to be placed on the second button 3 - and so on. 4 5 6 7 8 9 10-Subprog to be placed on the last button [Blank line] [Blank line] 'Subprog name' (List of names to appear on rotating selector) 'Subprog name' 'Subprog name' etc. (As many as you like) [Blank line] [Blank line] [Blank line] * } By editing this file, your own selection of sub-progs can be chosen. @endnode @node DISK "Files and layout of the 'BlackBoard:' disk" @{u}Files on the 'BlackBoard:' device...@{uu} 'INIT' - Sets up the default files of the 'BBoard:' device. 'BlackBoard' - Main program. 'DRAWDATA' - This draws up a grey-scale image of the picture. Drawer 'Dithers'... Files (4096 bytes long) which contain the information for a certain dither-pattern. Drawer 'MC'... Machine code patches which are used to speed up essential parts of the programs. Drawer 'Subprogs'... Contains ALL the modules which are called. e.g 'FLIP' - Subprog which mirrors the image. 'flip.req' - If present this file tells 'BlackBoard' what information the subprog will need, and 'BlackBoard' finds out for it. Drawer 'Loaders' Drawer 'Savers' Drawer 'ColourSelectors' Drawer 'Displayers' These drawers contain more subprogs which can be run via the 'Load', 'Save', 'Palette' and 'Display'/ 'Preview' respectively. This device can be a single device (i.e a floppy disk) or just an assign on a hard drive. @{u}Files on the 'BBoard:' device....@{uu} This 'device' is checked for by the 'INIT' program when you run it. If it is not present then it will be assigned to the RAM: drive. If however you have a hard-drive you may wish to assign it to this. This has a number of advantages over the RAM: drive, the main ones being that it doesn't use up machine memory so that larger files can be edited and the fact that the data is maintained even if you switch off. However the disadvantage is that it is slower at accessing than the RAM: drive, so most functions will be slowed down. For this reason, although you can use a floppy disk as the 'BBoard:' device (and I have at times), it's not advised as it slows things down a lot. Anyway on this device are present information about the picture, including the picture itself. BB.red \ BB.gre | BB.blu | ---> These files contain the actual image data. It's stored as or | just a large block of data, each pixel being assigned BB.grey / a single byte - indicating it's intensity. (0=nothing,255= full). e.g For a colour picture 10 pixels across by 15 down. There will be a 'BB.red', a 'BB.gre' and a 'BB.blu' file each 150 bytes long. If the picture were a grey-scale one then there would be only one file - 150 bytes long and called 'BB.grey'. BBpal ---> This file contains the best 256 colours for a colour picture. Each colour is stored as 4 bytes. The first can be used for what ever you want (I don't use it). The second containing the red component (0-255), the second the green, and the third the blue. The colours are also in order. e.g If you want to display it in 64 colours take the first 64 colours. BBmapping --> This file contains the map for the picture. As I've already stated each pixel is stored as a value from 0-255. As standard the 0=nothing and 255=full on. However this relationship can be changed. This file contains 256 values the first telling you the intensity of pixels of value 0 (normally 0) and the last the intensity of pixels of value 255 (normally 255). BBdither --> This file contains the dither pattern to be used if both dithering is to be used AND its of the mapping type. The files first byte is a value between 0 and 7. This advises the displayer how much dithering is needed (7=maximum). The rest of the file is made up of 4096 bytes (64 * 64) which contain the dither matrix. See below for more info. BBinfo->A very important file. This file contains the information about the picture. It's arranged as follows. [WORD] - Width of the image. [WORD] - Height of the image. [WORD] - Bit 1 set = It's a grey-scale image. [WORD] - Bit 1 set = The picture should be displayed in Interlace. Bit 2 set = The picture should be displayed in Hi-res Bit 3 set = The picture should be dithered. Bit 4 set = If dithered - should be error-distribution NOT MAPPING (i.e don't need BBmapping file) [WORD] - Contrast of image (0-128) [WORD] - Brightness of image (0-128) [WORD] - Additional red in image (0-128) [WORD] - Additional green in image (0-128) [WORD] - Additional blue in image (0-128) BBsend --> This file contains the information requested by the .req file. BBerror --> If your program has an error (which you manage to catch) save the error text in this file and 'BlackBoard' will inform the user. @endnode @node WRIT "The .req file" Writing Your own modules ------------------------ What ever your sub-prog does - complex or otherwise there are certain guidelines it should try to abide by. Firstly if is alters any of the picture information it should subsequently update the BBinfo file and any of the other files which require it, so that other programs receive the correct information. It should also try to abide by the less important protocol. For example if it's a palette program you should try to organize the file so that the most colours are at the front. The modules can be written in any language PROVIDING that they can run by a simple CLI command (e.g 'RECTANGLE'.) The .req file ------------- Any subprog can ask the main program to get information for it. For example if you are writing a loader you will need at least a filename. You can ask the main prog to get this filename for you and pass it across to you. This is done by setting up a .req file. The main prog will look for this file before it runs the sub-prog. If it finds it it will save the required information in a file called 'BBoard:BBsend' were the sub-prog can access it via the dos-library. For example "Rectangle"s' file is called "rectangle.req" The basic structure of the .req file is as follows.... [WORD] = Number of bits of info wanted. e.g 1 [BYTE] = Type of data. 1 (A number) [STRING] = Prompt for user 'Number of times?' [STRING] = Default return. 'Click here' If you want another piece of information simply change the first value to 2 and put another [BYTE]-[STRING]-[STRING] structure on the end of the file. At present there are 7 types of data that can be gained (more will be added with future revisions of the program) Type 1= Numerical value (e.g Number of times) OUTPUT=A WORD Type 2= Area of picture (e.g To draw rectangle in) This is a bit of a weird one. If you chose this one then the next 4 inputs MUST be numerical. This is because the program stores in them the values from this function. You can call them what you like, but as the program will return them as X-coordinate, Y-coordinate, width and then height, you may as well call them that. For example a typical structure is... [BYTE]=2 - The area function [STRING]="Choose area" - Gadget text [STRING]=Anything - Ignored [BYTE]=1 - Numerical value 1 [STRING]="X-Coordinate" - The x-coordinate (top left) [STRING]="15" - Default value. [BYTE]=1 - Numerical value 1 [STRING]="Y-coordinate" - The y-coordinate (top left) [STRING]="15" - Default value. [BYTE]=1 - Numerical value 1 [STRING]="Width" - The width [STRING]="100" - Default value. [BYTE]=1 - Numerical value 1 [STRING]="Height" - The height [STRING]="100" - Default value. In this way the user can select an area with the mouse or can simply type in the values. This function alone has NO output. However the four values that are after it DO. Each one outputs a single WORD. Type 3= Filename. OUTPUT=A STRING Type 4= Switch. In this one the first text is made up of two options separated by a '|' (ASCII 124). The second string should contain either an '0' or a '1' (ASCII 48 or 49). The output is a WORD. If it ="0" then the first option has been chosen, if "1" then the second. e.g [BYTE]=4 - Switch function [STRING]="Rotate|Mirror" - The two options [STRING]="0" - Default options is "Rotate" Type 5= Pass through. This option has no OUTPUT and can't be selected by the user. The first text string appears as white text on a depressed button. (c.f The 'SAVE_ILBM' menu). It's function is to tell the program not to call the subprog straight away, but to get the current 'DISPLAY' routine to do it. All you need to know is that these functions will receive any other information they require from the main program not in 'BBoard:BBsend' but in 'BBoard:BBsend2'. This is because 'BBsend' is saved by the display routine and contains... [LONG] = Address of the screen structure. [BYTE] = Red content of colour register 0 [BYTE] = green content of colour register 0 [BYTE] = blue content of colour register 0 [BYTE] = red content of colour register 1 [BYTE] = green content of colour register 1 etc...until [BYTE] = blue content of colour register 255 This will be the same irrespective of how many colours are used. The save prog must look in BBinfo to find the amount of colours used. Type 6= Point. This will get the user to select a point from the data. Like option 2 this must be followed by other values to contain the info, in this case two type 1 options. Type 7= Square. This (like above) needs following values - this time three. The first two containing X and Y values of the box, and the last one the width(=height) of the box. Once the user is happy with the selection the subprog will be run. The information gained from the menus will be saved in the file 'BBoard:BBsend' (or 'BBoard:BBsend2'; see above). The structure of the file depends on the requests. For example if you asked for two numerical values (code 1) followed by a filename (code 3) then the file bbsend would be.. [WORD]=Result of first numerical question [WORD]=Result of second numerical question [STRING]=Filename selected from third question. @{u}Display Routines@{uu} These are different in two ways. Personally I'd leave this section unless you actually want to write one. Anyway. Firstly THEY CANNOT HAVE A .req FILE. Why? Well that's because if there is a BBsend file present when they are run it means that they are being asked to launch a program after they have displayed the screen. The BBsend file will contain just a single string. This string will be the FULL path of the program to be run (e.g "BlackBoard:SubProgs/Savers/Save_ILBM"). The displayer must save out another BBsend file which contains the screen address and the palette registers (see above) and then run this program. After the program has finished the displayer should (as per normal) close the screen, free any memory and finish. @endnode @end