ZPACK REFERENCE MANUAL 2.0 Written by Tim Meekins March 6, 1991 Copyright 1990,91 by Tim Meekins 1. WHAT IS ZPACK? ZPACK is an Apple IIgs Toolset which contains functions designed for packing and unpacking data blocks. The tool also contains functions for creating several different file formats. As of this release, there are functions for reading and writing ZPACK 1 (ZP1) file formats and for unpacking Apple Preferred Format pictures. ZP1 is a format for compressing standard Super Hi-Res pictures on an Apple IIgs. Future file formats will compress 3200 color pictures, variable sized pictures, sound samples, full screen animations, and other file formats. Also included in this distribution is ZPACK MASTER, a program which packs and unpacks the various ZPACK file formats. The source code for ZPACK MASTER is also included as a teaching aid in using these tools. 2. ZPACK MASTER ZPACK MASTER is a desktop application which provides a way for packing and unpacking the different ZPACK file formats. Version 2.0 currently supports the following features: o Loads uncompressed Super Hi-Res Pictures (SHR). o Loads Apple Preferred Super Hi-Res Pictures (APF). o Loads ZPACK 1 compressed SHR Pictures (ZP1). o Saves uncompressed Super Hi-Res Pictures (SHR). o Saves ZPACK 1 compressed SHR pictures (ZP1). o View Super Hi-Res pictures. ZPACK MASTER uses resources, therefore system software greater than 5.0 is required. Also included in the ZPACK distribution is the complete source code for ZPACK MASTER. The source is written in 65C816 assembly language using the Orca/M assembler and resource information is compiled using REZ from Apple Tools & Interfaces. 3. ZPACK FILE FORMATS 3.1 ZPack 1 File Format (ZP1) See supplemental document ÒA Description of the ZPACK 1 File Format.Ó 4. HOW DOES ZPACK WORK? [in a nutshell] ZPACK packs a block of data based on the bytes in a previously packed data block and on previous bytes in the current data block. For example, if two consecutive scanlines in a picture are identical, the second scanline would be packed as a single byte. Also, if a single data block contains a long sequence of repeated bytes, then only 3 bytes are needed. ZPACK currently implements 7 different packing algorithms, and will adaptively determine the best algorithm to use which minimizes the output space. Because of the optimal adaptive nature of ZPack, packing files may take a little time, whereas unpacking files may be done swiftly. 5. THE ZPACK TOOLSET. The ZPACK Toolset is a standard system Toolset (sorry Apple) and is tool set number 230. The toolset, TOOL230, should be copied to the SYSTEM/TOOLS directory like all other tools. Standard tool interfacing techniques are used to access the toolset. All examples will be given in 65C816 assembly language format, but all tools are callable from any language allowing tool calls. $01E6 ZPBootInit This should never be called by an application. $02E6 ZPStartUp entry: word: MemoryID SP-> -------------- exit:: no values returned. errors: $E601 ZPDupStartUp ZPack has already been started up. This starts up ZPack and initializes its variables. ZPack uses the Memory Manager; therefore, be sure a valid Memory ID is passed. ZPack will automatically dispose of all the memory that it allocates. $03E6 ZPShutDown This shuts ZPack down. Be sure this is called before exiting. Due to the architecure of ZPack, if an application does not shut down ZPack, then a future application will get a ZPDupStartUp error when trying to start up ZPack. errors: $E602 ZPNotStartUp ZPack wasn't started up. $04E6 ZPVersion entry: word: space for returned value SP -> ----- exit: word: VersionNum Stored in standard tool version format. This returns the version number of the tool. It is currently set to $0100. $05E6 ZPReset Resets ZPack. This is sort of mix between ZPStartUp and ZPShutDown. An application shouldn't ever make this call. $06E6 ZPStatus entry: word: space for result SP-> ---- exit: word: Status Returns TRUE if ZPack has been started up. $09E6 ZUnPack entry: word: BlockSize Size of unpacked data long: BlockPtr Pointer to the block to unpack to long: OldBlockPtr Pointer to the previous block long: BufferHandle Handle to the pack buffer SP-> ------------------ errors: $E602 ZPNotStartUp ZPack wasn't started up This tool function is used for unpacking a block of data that has been packed using ZPack. The user must supply the size of the unpacked block, and pointer to the block, a pointer to the previously unpacked block (or NIL), and a pointer to a pointer of where the unpacked data is to be stored. Note: When ZUnPack is finished, the pointer pointed to by BufferHandle, points to the end of the pack buffer. If OldBlockPtr is set to 0 (NIL pointer), then ZUnPack will create a block of size BlockSize containing all zeros. This zero block will be used as the old block is no previous or known block is known. $0AE6 ZPack entry: word: BlockSize Size of block to pack long: BlockPtr Pointer to the memory to pack long: OldBlockPtr Pointer to the previous block long: BufferHandle Handle to the pack buffer SP-> ------------------ errors: $E602 ZPNotStartUp ZPack wasn't started up This is the ZPack algorithm for cpacking a block of data. The user must supply the size of the block, and a pointer to the block, a pointer to the previously packed block (or NIL), and a pointer to a pointer of where the packed data is to be stored. Note: When ZPack is finished, the pointer pointed to by BufferHandle, points to the end of the pack buffer. Therefore, save the starting pointer, and from this new value you can get the length of the packed block, ie. PackedSize = [BufferHandle] - StartPtr. If OldBlockPtr is set to 0 (NIL pointer), then ZPack will create a block of size BlockSize containing all zeros for OldBlockPtr. $0BE6 ZP1Pack entry: long: space for return long: PicturePtr pointer to picture long: PackPtr pointer to packed buffer SP-> ------------- exit: long: PackSize Size of the packed data errors: $E602 ZPNotStartUp ZPack wasn't started up This tool function packs a super hi-res picture into the ZP1 format. $0CE6 ZP1UnPack entry: long: PicturePtr pointer to picture long: PackPtr pointer to packed buffer SP-> ------------- errors: $E602 ZPNotStartUp ZPack wasn't started up $E603 ZP1BadVersion ZP1 data was the wrong version $E604 ZP1notZP1 ZP1 data wasn't in ZP1 format This unpacks a super hi-res picture from ZP1 formatted data. $0DE6 ZP1LoadPic entry: long: PicturePtr pointer to picture long: FileName Pointer to a GS/OS class 2 filename. SP-> ------------- errors: $E602 ZPNotStartUp ZPack wasn't started up $E603 ZP1BadVersion ZP1 data was the wrong version $E604 ZP1notZP1 ZP1 data wasn't in ZP1 format Given a filename, this tool function will load from disk and unpack a ZP1 formatted file. $0FE6 APFUnPackMain entry: long: PicturePtr pointer to picture long: PackPtr pointer to packed buffer word: PackSize size of the packed buffer SP-> ------------- errors: $E602 ZPNotStartUp ZPack wasn't started up $E605 The MAIN block was not found. This unpacks the MAIN block containing a super hi-res picture from APF formatted data. 6. INTERFACING ZPACK THROUGH ASSEMBLY LANGUAGE. The following examples show how to access ZPack through assembly language. ZPack can be called using the two standard tool dispatcher entry points. Examples given will be using entry #1 located at $E10000. Loading and starting ZPack pha ldx #$0202 ;MMStartUp jsl $E10000 plx bcs error stx UserID pea $00E6 ;Tool 230 pea $0100 ;Version 1.0 ldx #$0E01 ;LoadOneTool jsl $E10000 bcs error lda UserID pha ldx $02E6 ;ZPStartUp jsl $E10000 bcs error and to shutdown... ldx #$03E6 ;ZPShutDown jsl $E10000 lda UserID pha ldx #$0302 ;MMShutDown jsl $E10000 Viewing a ZPack 1 picture can be as easy as... ... pea $00E1 ;Bank of SHR screen pea $2000 ;Address of SHR screen pea (filename)|-16 ;Bank of filename pea filename ;Address of filename ldx #$0DE6 ;ZP1LoadPic jsl $E10000 bcs error ... filename dc .... Of course, this all can be greatly simplified by using the Zavtra Macro Disk: MMStartUp @x bcs error stx UserID LoadOneTool (#230,#$0100) bcs error ZPStartUp UserID bcs error ... ZP1LoadPic (#$E12000,#filename) bcs error ... ZPShutDown MMShutDown UserID ... filename dc ... UserID ds 2 6. SHAREWARE FACTS AND LICENSING ZPACK. ZPACK MASTER is a shareware program and you, the user, are obligated to pay $10 if you feel the program is worth keeping and using. Make out all checks to "Tim Meekins". The mailing address is in the following section. The ZPACK toolset may be used within Public Domain programs for free if proper acknowledgment, such as ÒZPACK code written by Tim Meekins.Ó, is given in the program and documentation; otherwise, ZPACK may not be used. The ZPACK toolset can ONLY be used in a commercial software program, or other programs sold for profit, if a licensing agreement or written permission has been obtained from the author, Tim Meekins. Acknowledgment must also be given to the author in the program and documentation. 7. THE AUTHOR Tim Meekins is currently working on a Master of Science degree at Ohio State in computer graphics and animation. Tim is also the author of The Software Experience demos, the ZLaunch program launcher, the Z3D demo, and the Zavtra Macros Disk. He can be contacted at: Tim Meekins [ Zavtra Software] 8372 Morris Rd. Hilliard, OH 43026 (614) 878-6557 meekins@cis.ohio-state.edu timm@pro-tcc.cts.com meekins@bluemoon.uucp 8. REFERENCES Apple II File Type Notes, File Type $C0, Auxiliary Type $0002 Apple II File Type Notes, File Type $C1, Auxiliary Type $0000 Apple IIGS ToolBox Reference Manual, Volume 1, Pages 14-39 to 14-44. APW Tools [ & Interfaces] Reference Meekins, Tim, ÒA Description of the ZPack 1 File FormatÓ, Zavtra Software, 1991.