**************************** HeliOS DOS accessory library **************************** -------------------------------------------- A table of the functions contained in DOSLIB -------------------------------------------- The specific routines available from DOSLIB are listed below in a table with each routine presented as a descriptive name, the routine number, and a HeliOS Stack diagram showing parameter usage. LOADPP 0 FNAME[Counted](l), Buffer(l) - - - Buffer(l) GETPP 1 FNAME[Counted](l), MemType(l) - - - Buffer(l) LOADPIC 2 Various.....,Flag(w) - - - Flag(w) GETPIC 3 FileName(l),Flag(w) - - - Various...,Flag(w) UNPACKPIC 4 Various.....,Flag(w) - - - Flag(w) GETVIEWMODES 5 IFF File(l) - - - ViewModes(w) GETBMHEADER 6 IFF File(l) - - - BitMapHeaderPtr(l) GETCOLOURTABLE 7 IFF File(l),ColourTable(l) - - - Count(l) FINDCHUNK 8 IFF File(l),Chunkname(l) - - - Chunk(l)or(0) GETSCREENSIZE 9 BMHD(l),Modes(w) - - - Wid(w),Hgt(w),Modes(w) SCROLLSCREEN 10 Scrn(l), XScrl(w), YScrl(w) - - - GUESSVIEWMODES 11 Wid(w), Hgt(w), Depth(w) - - - ViewModes(w) FADECOLOURS 12 VPrt(l),ColTab(l),Delay(w),Flag(w) - - - SETCOLOURS 13 VPrt(l),ColourTable(l)(or 0) - - - Note: The names of the routines are for reference in this documentation only, and are NOT used as HeliOS Words. The routines are all called by using the KeyWord DOSLIB along with the routine number. *************************************************************************** ------------- HeliOS DOSLIB ------------- This library of routines implements several useful functions to automate the loading of DOS files and facilitate the loading, decoding, and display of IFF ILBM files. Some of these functions are screen and graphic handling routines, but they are grouped together here since they are used together with the IFF handling functions. -------------------------------------- Calling HeliOS DOS Library routines -------------------------------------- As with all HelIOS internal libraries, each DOS library routine has an associated reference number. In this documentation the functions are all given names for ease of reference, but you must remember that the names used here are NOT HeliOS command names, and all these functions are accessed from HeliOS by their library number alone. To call any routine simply use the command DOSLIB preceded by the reference number of the routine you want to call. The calling parameters for any routine should be placed on the stack immediately before the reference number of the routine. For example, GETPP is routine number "1" in the HeliOS DOS library, and requires the following parameters: GETPP ( FNAME[Counted](l), MemType(l) - - - Buffer(l) ) where FNAME is the 32-bit filename string pointer and MemType specifies the type of memory where you want the file to be loaded. So, to call GETPP you might say: MYFILENAME MEMCHIP 1 DOSLIB MYFILEBUFFER D! which expression is constructed as follows: MYFILENAME MEMCHIP 1 DOSLIB MYFILEBUFFER D! ^^^^^^^^^^^^^^^^^^ ^ ^^^^^^ Parameters Routine number HeliOS internal library call --------- A Warning --------- Some of the routines in this extension module are very powerful, with many features packed into single routines. Please take care to read this documentation thoroughly before using the extension routines. In particular GETPIC, LOADPIC, and UNPACKPIC do a lot of different things depending on how you set the bits in a control flag word. Once you are familiar with these routines, using them is very simple, but you do need to read ALL the documentation carefully since the HeliOS stack parameters for these functions will vary not only according to the control flag word bit settings, but also with success or failure. This is one occasion where jumping in without reading the instructions will probably result in failure. ------------------------------------------------------- An important note about RastPorts and BitMaps in DOSLIB ------------------------------------------------------- Various DOSLIB routines use RastPorts and BitMaps. In ALL cases these structure names refer to the COMPLETE STRUCTURE, with all the necessary associated bitplanes and sub-structures allocated. In NO case do we refer to instances of the RastPort or BitMap as bare empty structures with a simple single memory allocation. When DOSLIB creates a RastPort or BitMap for you, it will be complete and fully initialised, with bitplanes created and filled with data, all ready for you to use in any Amiga display routine. When DOSLIB expects a RastPort or BitMap pointer from you, it expects a complete structure with associated BitMap and bitplanes etc, such as is provided by the HeliOS OPENRPORT function. ---- N.B. ---- To deallocate a BitMap or RastPort created by DOSLIB you must deallocate not only the basic main structure, but also ALL associated structures and bitplanes etc. In the case of RastPort and BitMap structures created by the DOSLIB routines, you should call the HeliOS CLOSEBMAP and CLOSERPORT functions to deallocate the structures. A single call to CLOSEBMAP or CLOSERPORT will deallocate the BitMap or RastPort and all associated elements such as bitplanes etc. Please read the HeliOS documentation for OPENBMAP, OPENRPORT, CLOSEBMAP, and CLOSERPORT before using the DOSLIB routines. ---------------------------------- Memory allocation and deallocation ---------------------------------- The memory allocation by all DOSLIB routines employs the HeliOS memory management system and uses the ALLOCMEMORY function. All the memory allocated for you by DOSHLIB routines should be deallocated by using the HeliOS FREEMEMORY function. Because the HeliOS internal memory management system is used, all memory allocations will be cleared automatically when you exit HeliOS. Nevertheless you should always take care to deallocate your own memory within each program. ---- N.B. ---- It is easy to forget to deallocate memory which has been allocated automatically within these extension routines. In general, DOSLIB will allocate a buffer or structure then pass a pointer back to you. It is then your responsibility to deallocate the buffer or structure using FREEMEMORY when you have finished using it. In the case of RastPort and BitMap structures created by DOSLIB routines, you should call the HeliOS CLOSEBMAP and CLOSERPORT functions to deallocate the structures. A single call to CLOSEBMAP or CLOSERPORT will deallocate the BitMap or RastPort and all associated elements such as bitplanes etc. --------------------------------------- Notes on UNPACKPIC, GETPIC, and LOADPIC --------------------------------------- PLEASE READ THESE INSTRUCTIONS VERY CAREFULLY!!!! UNPACKPIC -> Unpack data from an already loaded IFF file. LOADPIC -> Load an IFF file and unpack into structures you supply. GETPIC -> Load an IFF file and unpack into structures it creates. These three routines offer very powerful functions for IFF ILBM file loading and manipulation. They are fast, productive, and very flexible, with completely automatic loading and decoding of IFF ILBM files into display structures etc. Like LOADPP and GETPP, all these routines will automatically sense and decrunch PowerPacked files. All three routines work in a similar fashion, but there are the following differences: UNPACKPIC and LOADPIC unpack IFF files into structures you supply. GETPIC auto-allocates display structures for you and loads the IFF data. In general these routines automatically load and unpack IFF ILBM files into any or all of several structures required for the Amiga graphic display. The routines may be passed various structures to be filled, or you may specify that the structures be automatically created for you. Deallocation of the structures created for you by these functions: In the case of simple blocks of allocated memory such as ColourTables and BMHeader structures, DOSLIB memory allocation uses the HeliOS ALLOCMEMORY function. In these cases deallocation should always use the HeliOS FREEMEMORY function. In the case of RastPort and BitMap structures created by these DOSLIB routines, you should call the HeliOS CLOSEBMAP and CLOSERPORT functions to deallocate the structures. A single call to CLOSEBMAP or CLOSERPORT will deallocate the BitMap or RastPort and all associated elements such as bitplanes etc. The different possible functions of UNPACKPIC, GETPIC, and LOADPIC need careful attention to stack control. These routines function variously according to bits set in a control flag word which is passed as the top HeliOS stack parameter. Using this control parameter you can instruct the routines to unpack IFF File data into (and allocate if required) any of the following: Bitmap RastPort ColourTable BMHeader ViewModes The flag word determines both what is created or decoded, and also what parameters are expected and returned on the stack. In other words, these routines do not have a fixed stack usage, so you have to be a little more careful than usual. Error returns: These routines return a "result flags" word which notifies the calling program of what has happened. In general, a successful operation will result in the returned flag word bits being set to correspond with the control flag word passed at the start. If any of the bits of the flag word returned is different from the corresponding calling flag word bit you know that there has been an error in that part of the operation. The individual bits of the control flag word indicate which specific structures are to be created or filled, and the corresponding bits of the return flag word indicate the success of the operations which the particular bits control. As each routine goes through the (sometimes fairly lengthy) sequence of operations requested, the bits of the result flags word are set as each operation succeeds. If any sub-operation fails, an attempt will be made to clear up any allocations already made, clearing the associated bits of the result flags word before exiting gracefully. This means that if ALL your requested operations are not successful, the routine should abort and leave a null result flag word and nothing else on the HeliOS stack. This is the normal error return status, and indicates that the routine has exited gracefully and closed down anything it may have allocated. If, upon error, any bits remain set in the result flags word, this will probably indicate that for some reason the routine was unable to close down "gracefully". In the highly unlikely event that you repeatedly get a result like this, you should investigate the cause very carefully. By far the most common cause for an error is the failure of the most basic and obvious requirement: the IFF file must contain the required information and be correctly formed. The IFF files being decoded must contain appropriate information if auto BitMap, RastPort, ColourTable, BMHeader, or ViewModes are asked for. This is fairly obvious: if the file has no CMAP chunk, the routines will not be able to sensibly create a ColourTable, etc. Unfortunately it is not uncommon to find defective or non-standard IFF files, so if you do get problems with these DOSLIB routines, please check the IFF files you are working with: you may be surprised at what you find! ---------------------------------------------------------- Using the control flags for LOADPIC, GETPIC, and UNPACKPIC ---------------------------------------------------------- Here are the control flag bit allocations: Bit0 = Force Continuous Bitplanes (Bob Format) in any allocated BitMap N.B. Only ONE of the following RastPort/BitMap can be requested. Bit1 = Allocate BitMap and decode IFF picture into it Bit2 = Allocate RastPort and decode IFF pic into it Bit3 = Allocate and fill ColourTable (16-bit RGB values) Bit4 = Allocate and fill BMHeader structure Bit5 = Return ViewModes word N.B. Input Flag determines action AND stack effect. In other words the stack parameters vary according to the control flag bits. For example, stack items such as BMap, RastPort etc will only be present if specified by the associated flag bits. Here are the result flag bit allocations: Bit0 = Continuous Bitplanes Used OK Bit1 = Bmap Decoded/Created OK Bit2 = RastPort Decoded/Created OK Bit3 = ColourTable Decoded/created OK Bit4 = BMHeader Decoded/created OK Bit5 = ViewModes Word returned N.B. Generally the result flag word will be identical with the control flag word if the operation is successful. Generally the result flag word will be null if the operation is not successful. Partial success for these routines is not possible. ALL operations requested must be successful, or FAILURE will be flagged and all resources de-allocated. ---------------------------------------------------------- Special notes on the usage of individual control flag bits ---------------------------------------------------------- Bit 0 - This bit, if set, will force all allocated bitplanes to be placed end to end within one contiguous block of memory, in BOB format as used, for example, by the Amiga GELS routines. Bit 1 - Bit 1 and Bit 2 deal with unpacking IFF data into either a Bit 2 BitMap or a RastPort. These bits work alternatively, so you can have either one but not both - take care! You can set neither of them if you wish, but if you try to set them BOTH, the BitMap alternative will be taken as the default mode of operation. Bit 1 - Bit 1, if set, will indicate that a BitMap structure (including bitplane memory) is to be allocated automatically by GETPIC, or that you are providing a BitMap structure and bitplanes yourself for LOADPIC and UNPACKPIC to initialise and fill. The IFF file will be parsed and picture data will be unpacked into the BitMap structure and the bitplanes. The result will be a fully initialised BitMap structure with all the bitplane data loaded, all fully ready to use as an Amiga display element. If Bit 1 is set, take care to note that the BMap(l) parameter shown in the stack diagrams will be present. If Bit 1 is NOT set, the BMap(l) parameter shown in the stack diagrams will not be present, and no BitMap operations will be undertaken by GETPIC, LOADPIC and UNPACKPIC. Bit 2 - Bit 2, if set, will indicate that a RastPort structure (including bitplane memory) is to be automatically allocated by GETPIC, or that you are providing a RastPort structure and bitplanes yourself for LOADPIC and UNPACKPIC to initialise and fill. The IFF file will be parsed and picture data will be unpacked into the RastPort structure and the bitplanes. The result will be a fully initialised RastPort structure with all bitplane data loaded, all ready to use as an Amiga display element. If Bit 2 is set, the RPort(l) parameter shown in the stack diagrams will be present. If Bit 2 is NOT set, the RPort(l) parameter shown in the stack diagrams will not be present, and no RastPort operations will be undertaken by GETPIC, LOADPIC and UNPACKPIC. N.B. Remember that if you set BOTH "Bit 1" and "Bit 2" by mistake, the "Bit 2" parameter will be ignored, and only "Bit 1" will be interpreted. In this case the result flag will only have "Bit 1" set, but the operation will NOT FAIL! This is one case where the result flag and the control flag may be different even though the operation was successful overall. It is best to avoid this situation by not making the mistake of setting both the bits 1 and 2 in the control flag word! Bit 3 - This bit, if set, will indicate that a ColourTable is to be allocated automatically by GETPIC, or that you are providing a ColourTable yourself for LOADPIC and UNPACKPIC to fill. The IFF file will be parsed and colour data will be unpacked into the ColourTable as a series of 16-bit RGB values. If this bit is set, the ColourTable(l) parameter shown in the stack diagrams will be present. If this bit is NOT set, the ColourTable(l) parameter shown in the stack diagrams will not be present, and no ColourTable operations will be undertaken by GETPIC, LOADPIC and UNPACKPIC. Bit 4 - This bit, if set, will indicate that a dummy BMHeader structure is to be allocated automatically by GETPIC, or that you are providing a dummy BMHeader structure yourself for LOADPIC and UNPACKPIC to fill in. The IFF file will be parsed and its BMHeader data will be copied into the dummy BMHeader structure. If this bit is set, the BMHeader(l) parameter shown in the stack diagrams will be present. If this bit is NOT set, the BMHeader(l) parameter shown in the stack diagrams will not be present, and no BMHeader operations will be undertaken by GETPIC, LOADPIC and UNPACKPIC. Bit 5 - This bit, if set, will indicate that a ViewModes word is to be returned by GETPIC, LOADPIC, or UNPACKPIC. The IFF file will be parsed and ViewModes determined from its CAMG chunk if present. If no CAMG chunk is present, an attempt will be made to guess appropriate ViewModes by analysing the IFF BMHD chunk. If this bit is set, the Modes(w) parameter shown in the stack diagrams will be present. If this bit is NOT set, the Modes(w) parameter shown in the stack diagrams will not be present, and no ViewModes operations will be undertaken by GETPIC, LOADPIC and UNPACKPIC. -------------------- Important Reminders! -------------------- 1. Remember that if ANY of the requested operations fail, the result flags word should normally be null. In the event of such a failure, there will be NO output parameters returned, just the flags word. 2. The return flags word should be identical with the control flags word in most cases except that: Bit 2 will NOT be set in the return flags word if BOTH "Bit 1" and "Bit 2" have been set in the control flags word by mistake. This means that you can have a successful outcome even if you do mistakenly set both bits 1 and 2, but this will cause your result flags word to differ from the control flags word! ************************************************************************* ********************************************* A detailed description of the DOSLIB routines ********************************************* Below is a detailed description of all the DOSLIB routines. At the start of each description is the routine number followed by the documentation name for the function. ************************************************************************* [ 0 ] ------ LOADPP ( FILENAME[Counted](l), BUFFER(l) - - - BUFFER(l) or NULL ) ------ Where: FILENAME = Pointer to counted filename string BUFFER = Pointer to pre-allocated buffer where the file is to load This function: * Is a general purpose routine for loading standard DOS files, and it will also handle and unpack files pre-crunched using PowerPacker. * This function will automatically detect and decrunch PowerPacker files without you having to worry about whether the files are crunched or not. * Loads (and unpacks) the file into a buffer supplied by you * LOADPP uses the first 16 bytes of the buffer supplied as "header" space. This means that you MUST supply a buffer of 16 bytes MORE than the total decrunched length of the file to be loaded. * LOADPP will store the total file size (including the 16 byte buffer header) in the first 4 bytes of the buffer, with the next 12 bytes of the buffer header free for you to use however you wish. * Remember that the file body starts at BufferStart+16, and that the total file size + 16 is always stored in the first longword of the buffer. * Returns a 32-bit pointer to the buffer start for success * Returns 32-bit NULL for failure -------- WARNING! -------- LOADPP does NO FILE LENGTH CHECKING, so take care to supply the correct length buffer, or use GETPP instead. LOADPP is designed to be used when you are loading files the uncrunched length of which you already know. ------- Example ------- An example of using LOADPP might be: FILENAME FILEBUFFER D@ 0 DOSLIB D0<> - this leaves a simple 16-bit flag on the stack for success or failure. ************************************************************************* [ 1 ] ----- GETPP ( FILENAME[Counted](l), MEMTYPE(l) - - - BUFFER(l) or NULL ) ----- Where: FILENAME = Pointer to counted filename string MEMTYPE = Type of memory where the file load buffer is to be created This function: * Is a general purpose routine for loading standard DOS files, and it will also handle and unpack files pre-crunched using PowerPacker. * This function will automatically detect and decrunch PowerPacker files without you having to worry about whether the files are crunched or not. * Loads (and unpacks) the file into a buffer allocated automatically * GETPP uses the first 16 bytes of the file buffer as "header" space. This means that the buffer will be 16 bytes LONGER than the decrunched length of the file to be loaded. * GETPP will store the total file buffer size (including the 16 byte header) in the first 4 bytes of the buffer, with the next 12 bytes of the buffer header free for you to use however you wish. * Remember that the file body starts at BufferStart+16, and that the total buffer size is always stored in the first longword of the buffer. * Returns a 32-bit pointer to the buffer start for success * Returns 32-bit NULL for failure * Remember that memory allocated by GETPP uses the HeliOS ALLOCMEMORY function, and should be deallocated by using the FREEMEMORY function. ------- Example ------- An example of using GETPP might be: FILENAME MEMCHIP 1 DOSLIB DDUP FILEBUFFER D! D0<> - this leaves a simple 16-bit flag on the stack for success or failure. This would automatically allocate a CHIP memory buffer and then load the file "FILENAME" into the buffer. If the file happened to be PowerPacked, it would be automatically decrunched ************************************************************************* [ 2 ] ------- LOADPIC ( See notes at start of this file! ) ------- The HeliOS Stack Diagram for LOADPIC is different depending upon how you set the command flags. The command flags determine which structures you supply on the stack to be filled by LOADPIC, so you must take particular care to set up the correct operation with flags corresponding to your supplied stack. Here is a stack diagram for the most elaborate version of LOADPIC: RPort/Bmap(l), ColourTable(l), BMHeader(l), FileName[Counted](l), Flag(w) - - - Modes(w), Flag(w) Where: RPort = An initialised RastPort, including plane allocations etc. BMap = An initialised BitMap, including plane allocations etc. ColourTable = A table of colour values, number_of_colours*2 in length BMHeader = A BMHeader structure to be filled from IFF file information FileName = Pointer to counted filename string Flag = Control flags for this operation, determining just which structures you are supplying to be filled. Modes = Screen modes word derived from IFF file information Flag = Corresponds to input flag if routine has succeeded This function: * Loads IFF ILBM file data into structures which you have already created and which you pass as parameters to the routine. * LOADPIC is a general purpose routine for loading standard IFF ILBM files, and it will also handle and unpack files pre-crunched using PowerPacker. * This function will automatically detect and decrunch PowerPacker files without you having to worry about whether the files are crunched or not. * Loads (and unpacks) the file into a buffer allocated automatically, fills in your requested structures from the IFF information, then unloads the file and deallocates the file buffer. * Uses a 16-bit flag value to determine what information is required. * The number of input parameters, and the presence of the Modes(w) output parameter will depend on the bits set in the input flag word. * Returns a 16-bit flag indicating which sub-operations have succeeded: for full success the output flag should be the same as the input flag. * An error will result in only the flags word being returned. * The Modes(w) output parameter will only be present if all operations are successful: otherwise only the flag word will be returned. * Control Flag Bits: Bit0 = Not used Bit1 = Decode into BitMap Bit2 = Decode into RastPort Bit3 = Decode into ColourTable Bit4 = Decode into BMHeader Bit5 = Return ViewModes word ------- Example ------- In this example LOADPIC is asking for a BitMap and a ColourTable to be filled (Bits 1 and 3), so the input stack contains a filename and also pointers to a BitMap structure and a ColourTable. If sucessful LOADPIC will load data from the IFF file into the structures you provide, ready for use in an Amiga display routine. BITMAP D@ COLOURTABLE D@ FILENAME 10 2 DOSLIB 10 = - this leaves a simple 16-bit flag on the stack for success or failure. BITMAP is a pre-allocated BitMap COLOURTABLE is number_of_colours*2 in length to recieve RGB colour values The flags word was decimal "10", or, expressed as binary, "1010" ^ ^ Bit 3 Bit 1 ************************************************************************* [ 3 ] ------ GETPIC ( See notes at start of this file! ) ------ The HeliOS Stack Diagram for GETPIC is different depending upon how you set the command flags. The command flags determine what structures will be returned on the stack by GETPIC, so you must take care to set up the correct operation with flags corresponding to your expected stack. Here is a stack diagram for the most elaborate version of GETPIC: FileName [Counted] (l), Flag(w) - - - BMHeader(l), ColourTable(l), RPort/Bmap(l), Modes(w), Flag(w) Where: RPort = An initialised RastPort, including plane allocations etc. BMap = An initialised BitMap, including plane allocations etc. ColourTable = A table of colour values, number_of_colours*2 in length BMHeader = A BMHeader structure filled in from IFF file information FileName = Pointer to counted filename string Flag = Control flags for this operation, determining just which structures you are supplying to be filled. Modes = Screen modes word derived from IFF file information Flag = Corresponds to input flag if routine has succeeded This function: * Creates display structures etc. and loads IFF ILBM file data into these structures according to your specified control flags. * GETPIC will automatically allocate and fully initialise all structures you request and then load data from the IFF file into the structures. * The fully prepared structures are then passed back to you as return parameters on the HeliOS stack. * GETPIC is a general purpose routine for loading standard IFF ILBM files, and it will also handle and unpack files pre-crunched using PowerPacker. * This function will automatically detect and decrunch PowerPacker files without you having to worry about whether the files are crunched or not. * Loads (and unpacks) the file into a buffer allocated automatically, allocates and fills your requested structures from the IFF information, then unloads the file and deallocates the file buffer. * Uses a 16-bit flag value to determine what information is required. * The number of output parameters will depend on the bits set in the input flag word. * Returns a 16-bit flag indicating which sub-operations have succeeded: for full success the output flag should be the same as the input flag. * An error will result in only the flags word being returned. * The Modes(w) output parameter will only be present if all operations are successful: otherwise only the flag word will be returned. * You must deallocate all returned structures later yourself, using the HeliOS words FREEMEMORY, CLOSEBMAP or CLOSERPORT. In the case of BitMap and RastPort structures, deallocation using the HeliOS CLOSEBMAP or CLOSERPORT functions will autoamatically take care of ALL details of deallocation, including bitplanes and all other associated allocations. For example, simply calling CLOSERPORT with a pointer to the RasPort on the HeliOS Stack will deallocate everything associated with the RastPort in the one function call. * Control Flag Bits: Bit0 = BitMap/RastPort should have continuous (BOB format) bitplanes Bit1 = Allocate and decode BitMap Bit2 = Allocate and decode RastPort Bit3 = Allocate and decode ColourTable Bit4 = Allocate and decode BMHeader Bit5 = Return ViewModes word ------- Example ------- In this example GETPIC is requesting that just a RastPort be created and filled (Bit 2): This function will accept a filename and return a fully initialised RastPort with the IFF image loaded into it. FILENAME D@ 4 3 DOSLIB 4 = IF RASTPORT D! 1 ELSE 0 THEN - this leaves a flag on the stack for success or failure. The flags word was decimal "4", or, expressed as binary, "100" ^ Bit 2 ************************************************************************* [ 4 ] --------- UNPACKPIC ( See notes at start of this file! ) --------- The HeliOS Stack Diagram for UNPACKPIC is different depending upon how you set the command flags. The command flags determine which structures you supply on the stack to be filled by UNPACKPIC, so you must take particular care to set up the correct operation with flags corresponding to your supplied stack. Here is a stack diagram for the most elaborate version of UNPACKPIC: RPort/Bmap(l), ColourTable(l), BMHeader(l), FileBuffer(l), Flag(w) - - - Modes(w), Flag(w) Where: RPort = An initialised RastPort, including plane allocations etc. BMap = An initialised BitMap, including plane allocations etc. ColourTable = A table of colour values, number_of_colours*2 in length BMHeader = A BMHeader structure to be filled from IFF file information FileBuffer = Pointer to start of IFF file loaded into memory buffer Flag = Control flags for this operation, determining just which structures you are supplying to be filled. Modes = Screen modes word derived from IFF file information Flag = Corresponds to input flag if routine has succeeded This function: * Unpacks already loaded IFF ILBM file into structures which you have already created and which you pass as parameters to the routine. * Remember that if you used the DOSLIB GETPIC or LOADPIC routines to get the IFF file into a buffer, the pointer to the file start required by UNPACKPIC will be THE ACTUAL START OF THE IFF DATA. This will be 16 bytes after the start of the buffer, and not the buffer start itself! * Uses a 16-bit flag value to determine what information is required. * The number of input parameters, and the presence of the Modes(w) output parameter will depend on the bits set in the input flag word. * Returns a 16-bit flag indicating which sub-operations have succeeded: for full success the output flag should be the same as the input flag. * An error will result in only the flags word being returned. * The Modes(w) output parameter will only be present if all operations are successful: otherwise only the flag word will be returned. * The file buffer you supply will NOT be deallocated by UNPACKPIC. * Control Flag Bits: Bit0 = Not used Bit1 = Decode into BitMap Bit2 = Decode into RastPort Bit3 = Decode into ColourTable Bit4 = Decode into BMHeader Bit5 = Return ViewModes word ------- Example ------- In this example UNPACKPIC is asking for a BitMap and a ColourTable to be filled (Bits 1 and 3): This function will accept a pointer to a file buffer, and pointers to a BitMap structure and a ColourTable. If sucessful UNPACKPIC will load data from the buffered IFF ILBM file into these structures, ready for use in an Amiga display routine. BITMAP D@ COLOURTABLE D@ FILEBUFFER D@ 10 4 DOSLIB 10 = - this leaves a flag on the stack for success or failure. BITMAP is a pre-allocated BitMap COLOURTABLE is number_of_colours*2 in length to recieve RGB colour values The flags word was decimal "10", or, expressed as binary, "1010" ^ ^ Bit 3 Bit 1 ************************************************************************* [ 5 ] ------------ GETVIEWMODES ( FileBuffer(l) - - - Modes(w) ) ------------ Where: FileBuffer = Pointer to start of IFF file data loaded in memory buffer. Remember that if the file was loaded using DOSLIB functions the IFF data will start 16 bytes after the start of the memory buffer. In this case you will need to pass a pointer of "BufferStart+16" to GETVIEWMODES. Modes = Screen modes word derived from IFF file information This function: * Takes as it sole parameter a pointer to the start of an IFF ILBM file which has been loaded into a memory buffer. * Returns a word which represents a "best guess" at the correct ViewMode with which to display the IFF picture. * GETVIEWMODES will try to locate a CAMG chunk in the IFF file. If this is successful, the ViewMode specified in the CAMG chunk will be returned. If there is no CAMG chunk in the IFF file, an attempt will be made to guess appropriate ViewModes by analysing the IFF BMHD chunk. ------- Example ------- FILEBUFFER D@ 5 DOSLIB MYVIEWMODES ! ************************************************************************* [ 6 ] ----------- GETBMHEADER ( FileBuffer(l) - - - BMHeader(l) ) ----------- Where: FileBuffer = Pointer to start of IFF file data loaded in memory buffer. Remember that if the file was loaded using DOSLIB functions the IFF data will start 16 bytes after the start of the memory buffer. In this case you will need to pass a pointer of "BufferStart+16" to GETBMHEADER. BMHeader = Pointer to the IFF file BMHD chunk, if found. This function: * Takes as it sole parameter a pointer to the start of an IFF ILBM file which has been loaded into a memory buffer. * Returns a pointer to the BMHD chunk of the IFF file, or null if no such chunk is found. ------- Example ------- FILEBUFFER D@ 6 DOSLIB IFFBMHEADER D! ************************************************************************* [ 7 ] -------------- GETCOLOURTABLE ( FileBuffer(l), ColourTable(l) - - - Count(l) ) -------------- Where: FileBuffer = Pointer to start of IFF file data loaded in memory buffer. Remember that if the file was loaded using DOSLIB functions the IFF data will start 16 bytes after the start of the memory buffer. In this case you will need to pass a pointer of "BufferStart+16" to GETBMHEADER. ColourTable = A table of colour values, number_of_colours*2 in length, pre-allocated and supplied by you. This function: * Takes two parameters: a pointer to the start of an IFF ILBM file which has been loaded into a memory buffer, and a pointer to a memory buffer (ColourTable) supplied by you, into which the routine will copy colour information from the IFF CMAP chunk. * GETCOLOURTABLE will try to locate a CMAP chunk in the IFF file. If this is successful, the colours will be unpacked into your colour table buffer. * If there is no CMAP chunk in the IFF file, a error will be returned. * GETCOLOURTABLE returns the number of colours copied. ------- Example ------- FILEBUFFER D@ COLOURTABLE D@ 7 DOSLIB COLOURCOUNT D! ************************************************************************* [ 8 ] --------- FINDCHUNK ( FileBuffer(l), Chunkname(l) - - - Chunk(l)or(0) ) --------- Where: FileBuffer = Pointer to start of IFF file data loaded in memory buffer. Remember that if the file was loaded using DOSLIB functions the IFF data will start 16 bytes after the start of the memory buffer. In this case you will need to pass a pointer of "BufferStart+16" to GETBMHEADER. ChunkName = Longword containing ASCII representation of the chunk name. This function: * Takes two parameters: a pointer to the start of an IFF ILBM file which has been loaded into a memory buffer, and a longword containing the ASCII representation of the four letters which make up the chunk name. N.B. As an example of this, if you wanted to find the 'BMHD' chunk you would put the string "BMHD" into the longword parameter, and NOT a pointer to the string. * FINDCHUNK returns a pointer to the start of the chunk requested, or null for failure if a chunk with the specified name is not found. ------- Example ------- CREATEL CAMGSTRING ASCII C C, ASCII A C, ASCII M C, ASCII G C, FILEBUFFER D@ CAMGSTRING 8 DOSLIB IFFCAMGCHUNK D! ************************************************************************* [ 9 ] ------------- GETSCREENSIZE ( BMHD(l), Modes1(w) - - - Wid(w), Hgt(w), Modes2(w) ) ------------- Where: BMHD = Pointer to start of a BMHeader structure Modes1 = Original image screen modes word Wid = Screen width Hgt = Screen height Modes2 = Suggested final image screen modes word This function: * Takes two parameters: a pointer to a BMHeader structure and a ViewModes word for the image to be displayed. * GETSCREENSIZE returns three parameters, giving suggested width, height, and ViewModes for the optimal display of your image. * This routine tries to work out the best possible screen display for a particular image. In doing this it examines the ViewModes and BMHeader for the image data, which you pass as input parameters to the routine, and it also examines the current workbench display. * If possible GETSCREENSIZE will return a display mode which allows the whole, or as much as possible, of any image to be shown at once. To do this it may, for example, return a high resolution display mode to show an oversized low resolution image all on screen at once. As an example of this, you may have an IFF file specifying a 480x300 pixel image originally created in low resolution (320x200) mode. If you were to display this image in its original mode, you would only see part of the image on screen at any one time, and you would have to scroll around to view all of the oversized image. GETSCREENSIZE would look at this situation and would return if possible a high resolution ViewMode, so that you could display the whole image on screen at once. ------- Example ------- BMHEADER D@ VIEWMODES @ 9 DOSLIB NEWVIEWMODES! NEWHEIGHT ! NEWWIDTH ! ************************************************************************* [ 10 ] ------------ SCROLLSCREEN ( Screen(l), XScroll(w), YScroll(w) - - - ) ------------ Where: Screen = Pointer to screen structure. XScroll = Amount of desired X scroll. YScroll = Amount of desired Y scroll. This function: * This routine takes three parameters: a pointer to a Screen structure and two values for X and Y coordinate scroll offsets. * The purpose of this routine is to scroll a screen display around a large custom bitmap. * SCROLLSCREEN is fully automatic, and will check scroll limits and adjust the scroll accordingly before remaking the Amiga display to reflect the new scroll position. * You would normally use this routine after reading the keyboard cursor keys, for example, to scroll and update the display automatically. ------- Example ------- DISPLAYSCREEN D@ XSCROLL @ YSCROLL @ 10 DOSLIB ************************************************************************* [ 11 ] -------------- GUESSVIEWMODES ( Width(w), Height(w), Depth(w) - - - Modes(w) ) -------------- Where: Width = Image width Height = Image height Depth = Image bitplane depth Modes = Suggested final image screen modes word This function: * Takes three parameters: the width, height, and bitplane depth of the image to be displayed. * GUESSVIEWMODES will try to work out the optimum ViewMode for the image, and leaves the suggested ViewMode word as its return parameter. ------- Example ------- WIDTH @ HEIGHT @ PLANECOUNT @ 11 DOSLIB VIEWMODES ! ************************************************************************* [ 12 ] ----------- FADECOLOURS ( ViewPort(l), ColourTable(l), Delay(w), Flag(w) - - - ) ----------- Where: ViewPort = Pointer to ViewPort structure whose colours you wish to fade. ColourTable = Colour table defining the "target" colours. Delay = Delay to set fade speed, in multiples of 1/50 of a second Flag = Whether to fade colours in (=1) or out (=0) to black. This function: * Takes four parameters: The ViewPort whose colours are to be faded in or out The ColourTable defining the colours A delay value, in "ticks" used by the DOS "Delay" function A flag specifying whether to fade in (flag=1) or fade out (flag=0) * FADECOLOURS will fade in or out colours for the specified ViewPort. * The "end" neutral colour is black, and a delay parameter allows the fade to be controlled in increments of 1/50th sec. * This routine is useful as an accessory to a simple IFF viewing program where elaborate fades and wipes are not required. * FADECOLOURS deduces the number of colours to be "faded" from the ViewPort parameters, and will try to read the appropriate number of colours from the supplied colour table. * It is your responsibility to ensure that the colour table which you supply has the correct number of colours. ------- Example ------- VIEWPORT D@ COLOURTABLE D@ FADEDELAY @ IN_OUT_FLAG @ 12 DOSLIB ************************************************************************* [ 13 ] ---------- SETCOLOURS ( ViewPort(l), ColourTable[or 0](l) - - - ) ---------- Where: ViewPort = Pointer to ViewPort structure whose colours you wish to set. ColourTable = Colour table defining the "target" colours. This function: * Takes two parameters: the ViewPort whose colours are to be set and a Colourtable defining the colours. * SETCOLOURS sets the colours for the specified ViewPort from the supplied colour table. * If you specify a "null" for the ColourTable parameter, all the colours will be set to zero, or "black". * SETCOLOURS deduces the number of colours to be "set" from the ViewPort parameters, and will try to read the appropriate number of colours from the supplied colour table. It is your responsibility to ensure that the colour table which you supply has the correct number of colours. ------- Example ------- VIEWPORT D@ COLOURTABLE D@ 13 DOSLIB *************************************************************************