💾 Archived View for mirrors.apple2.org.za › archive › apple.cabi.net › Graphics › ZPACK2 › ZPACK.REF… captured on 2024-05-10 at 15:26:10.
⬅️ Previous capture (2023-01-29)
-=-=-=-=-=-=-
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.