Coding - ZXA library: a library for creating and playing animations.

<b>Coding</b> - ZXA library: a library for creating and
playing animations.

               ZXA library



              0. Entry

 As you probably guessed it - here
I'll tell you about what is
ZXA library and how you can use
it into their programs.

 However, for starters, if you have not
done - I strongly advise you
read the article "Packing animations JAM"
to understand what exactly
will talk further. In addition it would be
very good if you are also pre-
Read "About Libraries". If
all of you have already done so - read on.


            1. Overview

 So, what is ZXA library. This
freely distributed in source code
Library for creating and
playing animations. The library consists
of 2 parts:
 1) Packer and animation viewer. This part
library is written in Borland Pascal v7.0
on the PC.
 2) Players animations. This part is written in
Speccy in TASM v4.12 by RST7/CBS.
 Thus to use this
library you are, unfortunately, necessarily
will have access to a PC (or his
Emulator). However, if you think about it
not such an impossible condition - all
still animation, as a rule, are not
on the Speccy, but on more powerful machines. For
of the packer and the viewer will be animated
enough any PC, from 386 to
1mb memory and 256kb VGA graphics card. Except
that will go any PC emulator for the Amiga
or Apple Macintosh.
 In addition, in order to use
ZXA library you have to work in TASM'e
or try to port it at that
assembler, in which you work. Here
The fact that ZXA library written in such a way
as, in my opinion, should be written in any
a good library - it can be
completely reconfigured for the needs of
specific user without the intervention
in its code. Naturally, all this is done
through macros and conditional compilation, and
it currently supports the full
As only two assembly: TASM v4.12 by
RST7/CBS and ALASM v4.2 by Alem (modified by
KVA / E-Mage). In principle ZXA library completely
can be transferred to almost ALASM v4.2
without losing its flexibility (everything will be
work except for one thing, but on
below). However, I did not do
due to lack of time, and also because
that the existing converter is in no ALASM
supports the extension syntax ALASM'a
Version 4.2.

 Despite the fact that the library consists of
2 parts - there will be described in detail
only the part that concerns Speccy.
Description of the packer and animations for the viewer
PC can be found in the annex, in the archives with
programs and source code for the PC.

 All components are placed in the Library
application and represent 4 Archive:

ZXApcEXE.ZIP - Compiled and prepared
 to use the file wrapper and the viewer
 animations. Will be useful for those who do not
 wants to deal with the work of the packer, and
 just want to use it for their
 needs.
ZXApcSRC.ZIP - Sources packer
 and animation viewer for the PC. Necessary for those
 who wants to understand their work and,
 may use for their purposes.
ZXAanims.ZIP - Several examples of animations
 to showcase the work of the library. May
 be used both for the PC, and for
 Speccy.
ZXA_src. ZIP - The source code itself ZXA library
 and several examples to demonstrate its
 opportunities.

ZXApcEXE.ZIP and ZXApcSRC.ZIP packed
PKZIP'om on the PC, ZXAanims.ZIP and ZXA_src.ZIP
packed ZxZip'om.


        2. The library

 ZXA library provides the user
following functions:
 - Play animations in 3 modes:

   - Conventional Animation

   - Interlaced animation

   - C64 like animation
 - Any of the above players

   can work as one, and with

   two screens. In the latter case

   You can automatically change

   visible screen after displaying the next

   frame. In the derivation of the animation for one

   screen, you can choose - on which one.
 - Any type of animation can be played

   in any sequence of frames.
 - Animations can be placed in page-

   memory (even if the animation is displayed on the

   two screens).
 - There is a mode in which all used

   tables and procedures are in

   low memory (# 6000 - # 7FFF) for

   to free up more space for

   placement of the animation.
 - Animations can be divided into memory

   into several parts, these parts are even

   may be located in different pages

   memory!
 - The size of the playing animation is limited

   256 frames.
 - Size of frame animation for Interlaced and

   C64 like players can be anything, for

   a normal player, while displaying animation

   using both screens

   frame in the uncompressed state can

   be no more than # 1280 bytes (about

   24x24 or 32x18 familiarity).
 - All players use the stack for accessing

   to the data, but it is possible

   use a special handler IM2

   to prevent deterioration of information in

   arrival interrupts. Thus All Players

   can be used when included IM2

   interrupts.
 - All configuration parameters of the library

   through redefinition

   configuration variables without any
   any interference in the code library!
 - In the case of incorrect assignment of values

   configuration options when compiling

   will receive a message

   and recommendations for its removal.

   Incidentally, it is impossible in the

   ALASM'e.
 - Copies of all library modules are well

   comment and have a short description

   features work with each of them.
 - Along with the code module library is

   several examples of their use.

   Looking at them you can see that

   amount of code required for

   play the animation is in

   average only 20-30 lines.
 - Time frame for decompression test

   animations on Pentagon'e is slightly

   more interrupts.

 ZXA library consists of the following modules:
MEMORY.A - Makrobiblioteka realizing

             mechanism for allocating memory

             in the program.
ZXA_EQUS.A - This file contains all

             configuration variable,

             necessary for all modules

             ZXA library.
ZXA_1.A - player is normal and interlaced

             animation on one screen.
ZXA_2.A - player is normal and interlaced

             animations on two screens.
ZXA_C64.A - C64 like player animations.
ZXA_CODE.A - A set of additional procedures

             necessary for the players.
EXAMPLE1.A - An example of playing the usual

             or interlaced animation.
EXAMPLE2.A - Sample playback C64 like

             animation.
EXAMPLE3.A - An example of playing the animation

             consisting of two pieces.


       3. Use of the library.

 In order to use ZXA library in
their programs you will need:
 - Create and load ZXA animation.
 - Connect to your code files:

   - MEMORY.A and ZXA_EQUS.A. These files

     ensure the creation of all necessary

     for normal configure and compile

     All modules ZXA library.

   - One of the players: ZXA_1.A, ZXA_2.A or

     ZXA_C64.A. Which player should

     connect - it depends on how

     way was packed animation.

   - ZXA_CODE.A to create the necessary

     procedures for players.
 - Configure the code under the player is

   how they should work in your

   program.
 - Write a piece of code for initialization and

   playing an animation.
 - If you need to add to his
interrupt handler code for the correction
data on the stack, damaged on arrival
interrupts.

 Sample code for playing the animation:

; Include files with the necessary descriptions of

        . INCLUDE MEMORY

        . INCLUDE ZXA_EQUS


        ORG # 8000
; Initialize player code

        LD HL, ANIMATION; In HL - a pointer to the animation

        CALL ZXA_INIT
; Enables interrupt IM2

        DI

        LD HL, # BE00

        LD DE, # BE01

        LD BC, # 100

        LD (HL), # BF

        LDIR

        LD A, # C3; JP n

        LD (# BFBF), A

        LD HL, IM2; pointer to interrupt handler

        LD (# BFC0), HL

        LD A, # BE

        LD I, A

        IM 2

        EI
; ZXA_QFRAMES variable contains the number of frames
; In animation

        LD A, (ZXA_QFRAMES)

        LD B, A

        LD C, 0
LOOP PUSH BC

        HALT
; At the entrance to the procedure of drawing frame animation 
ZXA_DRAW_FRAME And in case you need to pass A number of the 
frame animation ; To be drawn.


        LD A, C

        CALL ZXA_DRAW_FRAME
, Proceed to the next frame

        POP BC

        INC C

        DJNZ LOOP

; All animation is lost - leave

        DI

        LD A, # 3F

        LD I, A

        IM 1

        EI

        RET

; Hooking up the player code and additional code

        . INCLUDE ZXA_1

        . INCLUDE ZXA_CODE

; IM2 Interrupt handler
; There is one subtlety. The fact that the handler
, Must be placed AFTER will be connected
; Code of a player. This is because the recovery code
; Any bad data stack is implemented as macros and
; Need to do so at the time of compilation
; Hook these macros have been defined.
; Danger error lies in the fact that if they were not
; Identified - their challenge will be perceived by the compiler
; As the definition label, everything will be compiled without
; Errors, and will result in a non-working code.
IM2
; A Macro that creates the code for data recovery

        _ZXA_IM2_START
; It can be placed all that needs to be done
; Interrupt handler.
; A Macro that creates the code for data recovery

        _ZXA_IM2_END
; Loads animation
ANIMATION

        . INCBIN anim

 That's all that needs to be done. As
see - all the elementary. True, as
everywhere, there are some nuances, but they
later. What is needed now to tell you about
general principles of the library and that
how to configure it to suit your needs.

            4. Operating principles

 Library loses ZXA animation in
all formats supported by the packer,
but with two restrictions. You can lose
only animation packed:
 - With vertical coding frame.
 - Packed with independent staff.
 In principle, the wrapper supports all
other methods of packaging (keys / a and a / h),
but in fact at the moment, these methods
have no practical value (even their
does not support viewer for PC).
 In principle, no particular problems with
in order to make support for animations
horizontal coding frames not
However, as I mentioned in an article on
animation package - quality of packaging
This mode is much lower.

 Because all the animation frames are packed
whatever - they can extract a
any sequence. Therefore, in ZXA
library does not function playback
animation, but there is only a function of extraction
shot by its number. So in order
to play the animation you need to
write your own main loop playback
animation (as was shown above in
example).

 Before you play the animation - it
to register. This is done
by calling the transfer ZXA_INIT
in HL pointer to the animation. If the animation
consists of several pieces - their
can be combined into one large animation
by calling for ZXA_ADD_FRAMES
each of the fragments. In the HL should
pass a pointer to the hook
animation, and in the A - frame number, starting with
that this animation will be inserted.
Number of fragments is not restricted, but
total number of frames in all fragments
limited to 256. The total number of frames per
animation, you can always learn from the variable
ZXA_QFRAMES. So that an ordinary piece of code
to connect the piece of animation will be
look like this:


        LD HL, ANIMATION_PART

        LD A, (ZXA_QFRAMES)

        CALL ZXA_ADD_FRAMES

 The difference between the functions and ZXA_ADD_FRAMES
ZXA_INIT is that, except ZXA_INIT
Among other things creates all the necessary
tables and procedures, so it must be
called before as to be called any
Another feature of the library. Also, it should be
cause, if after playing one
animation you want to lose another.

 All players that make up ZXA library
require for your work availability table
screen addresses. This table contains
currently addresses all the bytes in the screen that
enters frame animation, and is used for
draw a frame on the screen. Table size
is twice the size of the decompressed
frame, for example, frame size 10x16
familiarity table size will be:

           10 * 16 * 8 * 2 = 2560 bytes

 As players, in fact, still
What is the address listed in the table,
You can use this to
unpack the animation is not on screen, and in
any buffer. Simply fill
table of addresses of the buffer. Also
a simple remake of the table can be
get player to play animations
horizontal encoding frame.
 Table display default address
is a 7 page addresses # DB00,
immediately after the second screen. However, its
You can freely move to any other
a place where there is enough free memory.
The only exception: when using
any of the players for two screens
necessary that the table is located at 7
page (to make it available for
rendering a frame on the second screen). By the way,
precisely because of this the player can not
play animation with frame size
# 1280 more bytes, just not enough memory
under the table from the screen addresses.
 Location table in memory is given
two configuration variables:

ZXA_TABLE_PAGE - page number
ZXA_TABLE_ADR - address allocation table

 In addition to the table display address of the player
required memory for the various tables and
procedure. The size of required memory
depends on the specific configuration, but as
will employ at least a little more than kilobytes.
Player animations on one screen is required
the least memory, and they themselves are less
than those two screen. Most
memory requires the player C64 like animations
as In this case, unpacking the frame is
not on the screen and the clipboard, and then this buffer
drawn on the screen. Because of this
playing C64 like animation works
slightly slower than usual, but this is partly
offset by the fact that the actual size
frame in this mode is 4 times smaller than
visible on the screen.
 By default, all tables are placed in
"Slow" memory (# 6000 - # 7FFF), and all
procedure - a "fast" (# 8000 - # BFFF). But
In order to save so everyone needs to "fast"
Memory ZXA library has a special mode
in which everything - the tables and procedures
placed in the "slow" memory leaving
more space for the program. This
mode is activated the option:

           ZXA_ALL_IN_SLOW = YES


         5. Setting

 As already mentioned above - all the work
ZXA library can be controlled without
any interference in code modules
library. All you need to do to
configure the library code to your
needs - change the configuration
variables responsible for setting the code.

And for that, too, do not need to go into
code - the whole setup is as simple as
pereprisvaivaniem variables.
 All variables are described in the file ZXA_EQUS.A
and change their values only after
of how this file is connected to your
source code, but before be connected
any module library containing the code.
Furthermore ZXA_EQUS.A need to connect
also file MEMORY.A. This makrobiblioteka,
responsible for memory allocation in all
module library. Both of these files are not
contain a single line of code - only macros
and definitions of variables. Thus they can be, and
even need to connect at the beginning
your source, and all overriding
configuration variables are best
right after these podgruzki
modules. Here is how some will have to
look for your source code:

; Podgruzka modules with the necessary descriptions.
; Note that the order of their podgruzki should be just like 
that! 

        . INCLUDE MEMORY

        . INCLUDE ZXA_EQUS
; All necessary override the library
ZXA_USE_FRAME_BUFFER = YES
ZXA_FRAME_BUFFER_SIZE = 450

 A similar sequence of actions will
compiler the possibility to generate code
in accordance with your settings as
All the variables are changed to
moment of the beginning of the compilation of code modules
library.

 And now, direct what should
be discussed in this section.

Variable: ZXA_USE_FRAME_BUFFER
Default: NO
Affects: ZXA_1, ZXA_2, ZXA_C64
Purpose: Responsible for the allocation in the lower
memory buffer for the current packed
frame. If you set its value to YES,
then the memory will be allocated an additional
buffer, and before unpacking any
frame compressed data will be copied
in it, and will then be decompressed from
buffer. The creation of this buffer must be
when playing an animation on two screens,
and if the animation is in
paged memory.

Variable: ZXA_FRAME_BUFFER_SIZE
Default: 0
Affects: ZXA_1, ZXA_2, ZXA_C64
Purpose: Specifies the size of the frame buffer.
The value of this variable should not be
less than the maximum size of the packed
frame animation, but do not need to do
too much (waste of memory and
time since being transferred to the buffer block
Data size ZXA_FRAME_BUFFER_SIZE). In
If the buffer size is too
small - the consequences can be fatal.

Variable: ZXA_INTERLACED
Default: NO
Affects: ZXA_1, ZXA_2
Purpose: Specifies the type of animation for
Players ZXA_1.A or ZXA_2.A. Install it
value to YES, if you want to lose
interlaced animation. For a player ZXA_C64
this variable is not needed.

Variable: ZXA_ALL_IN_SLOW
Default: NO
Affects: ZXA_1, ZXA_2, ZXA_C64
Purpose: If this variable
is set to YES - tables and procedures
created by any player will be placed
in slow memory (# 6000 - # 7FFF). If NO,
the tables will be placed in the slow
memory, and procedures - in the fast.

Variable: ZXA_LARGE_ANIMATION
Default: NO
Affects: ZXA_1, ZXA_2, ZXA_C64
Purpose: If you want to lose
animation, which consists of several parts,
located in different pages of memory
need to set this variable
to YES. In this case, change the set of parameters
for functions and ZXA_INIT ZXA_ADD_FRAME: on
input, inter alia, the need
will transmit in register C Page
memory, which is animation, or
part of it. Ie call format is:

For ZXA_INIT: For ZXA_ADD_FRAME:

   LD HL, ANIMATION LD HL, ANIMATION_PART

   LD C, ANIMATION_PAGE LD C, ANIMATION_PART_PAGE

   CALL ZXA_INIT LD A, (ZXA_QFRAMES)

                                  CALL ZXA_ADD_FRAMES

Variable: ZXA_AUTO_FLIP_SCREEN
Default: YES
Affects: ZXA_2, ZXA_C64
Purpose: If the value of this
variable is YES, after unpacking
the next frame of animation will be switched
visible screen (after HALT'a course)
to display the results in
monitor. This is convenient because can not
take care of switching screens visible
himself. However, if for any
reasons is not desirable - you can set
this variable to NO. It should also be
remember that this variable has a meaning
only player animations using
two screens.

Variable: ZXA_TABLE_PAGE
Default: # 17
Affects: ZXA_1, ZXA_2, ZXA_C64
Purpose: The page number that will
create a table display of addresses. Remember
that the use of players for two
screens needed to table was
located in a page # 17!

Variable: ZXA_TABLE_ADR
Default: # DB00
Affects: ZXA_1, ZXA_2, ZXA_C64
Purpose: The address to which the memory
will be located on-screen table
addresses. By default, the table is
immediately after the second screen.
Variable: ZXA_USE_SECOND_SCREEN
Default: NO
Affects: ZXA_1, ZXA_C64
Purpose: Default player animations
for one screen is used to derive
first screen (with address # 4000). If
Set this variable to YES,
the output will be the second
screen (with address # C000 in page # 17).

Variable: ZXA_FRAME_XS
Default: 0
Affects: ZXA_C64
Purpose: The size of the frame animation X.
Given in familiarity. Possible values
lie in the range 1 .. 16.

Variable: ZXA_FRAME_YS
Default: 0
Affects: ZXA_C64
Purpose: The size of the frame animation Y.
Is defined in pixels. Possible values
lie in the range 1 .. 96. The values of these
two variables should be set only
when using the player as ZXA_C64 his
code must be adjusted to the size of
frame animation.

Variable: ZXA_C64_USE_BOTH_SCREENS
Default: NO
Affects: ZXA_C64
Purpose: If you want to lose the C64 like
animation on two screens - check this
variable to YES.

Variable: ZXA_CREATE_IM2_TABLE
Default: YES
Affects: ZXA_1, ZXA_2, ZXA_C64
Purpose: Responsible for the automatic
Generate table IM2 interrupt, as well as
stack for the handler IM2 interruption. By
default table and place the stack
created in memory automatically, but if
in your program interrupt table
should be located in a particular
address - you can disable the generation of
Table interrupts by setting the
this variable to NO. However, in this case
you have to manually allocate space for
stack an interrupt handler (it needs
somewhere 30-40 bytes) and write its index
a variable ZXA_IM2_STACK:


            LD HL, MY_IM2_STACK

            LD (ZXA_IM2_STACK), HL


               6. Remarks

 In principle, all written above is completely
enough to make full use ZXA
library in your programs. But there are a number of
subtleties in the use of the library,
which I have not said before. On them I
try to tell in this section.


                6.1 Memory

 ZXA library is written using
my makrobiblioteki - memory manager. About
Here you can read in detail in the article
Memory Management Library.
 On the one hand, it frees
the need to manually
allocate memory needed for the library
(And it is quite easy task, considering
abundance of adjustments related to the number and
Size of memory blocks). Here
as the entire mechanism for allocating memory
user's perspective, transparent and
In addition, the program is immune from
errors when allocating memory.
 However, on the other hand, this imposes
some restrictions on the program itself,
use the library. Simply put,
all memory allocation in your program
too, should take place only through my
makrobiblioteku! In principle, this should
be obvious - all memory allocation
in the program must be implemented by
one principle, otherwise we can
just get a bunch of glitches. Yes, and what
you have to use my manager
memory in my program, I feel great
dignity rather than disadvantage. The point
that when using a process
memory allocation in the program are very
greatly facilitated and becomes much
more visible. In addition the manager will
itself to monitor the memory and
report this at compile time, ie
you, in which case, do not have to look for
cause glitches in your program because
that the two tables overlap each
other.
 As you probably know, in the manager
put a certain pattern
memory. And this should be obvious
Conclusion: your program should reflect this
distribution scheme. Ie all blocks of your
program: the code, the memory allocated by
tables and procedures, a table of interrupts and
etc. should be placed in memory
accordance with the way it is laid in
memory manager. You can only save
that version 2.0 of my memory manager,
which was used in this library
can be completely reconfigured
under any scheme of allocation. So
that if the scheme of distribution,
installed in the manager by default you
does not fit - safely reconfigure its
and all the library code will be automatically
podstoen under the new scheme of distribution
memory.
 Also, do not forget that the standard
pattern memory means,
that the free memory you have starts with
Address # 6000, ie stack is located on the # 5FFF
or even lower. And the standard bootstrap
TASM'a stack is set to address # 61A7, so
that you have a choice: either to improve
loader TASM'a CLEAR VAL "24999" on
CLEAR VAL "24575" or add to your
program line:

         SET_SLOW # 61A8, # 8000, NO
immediately after. INCLUDE MEMORY
 I advise you to use the first option.


              6.2 Variables

 Any player ZXA library has several
variables, you may need
for their own needs. Here I show
brief descriptions for each of them:

ZXA_IM2_STACK. In this variable you must
Record pointer to a memory area
to be used by the handler
IM2 interrupt the stack. This must be done
only if you set the option
ZXA_CREATE_IM2_TABLE = NO and also want to
use macros and _ZXA_IM2_START
_ZXA_IM2_END Data recovery
spoiled by the advent of the interrupts.
 The size of the memory used by these
Macro is about 24 bytes
Add to that the stack size needed
for your code hook - and
you get the desired size of the stack. When
default setting stack size is not
exceed 62 bytes!

ZXA_IS_DRAW. This variable contains
# 01, if you are currently attending decompression
frame, and # 00 in any other case.

ZXA_QFRAMES. This variable contains the number of
the last existing frame of animation.
All, as I have said, may be 256
different frames randomly located
in memory. And may be registered under
any number, even forming a "hole" in
Table frames. And you can unpack the frame
with an arbitrary number - in which case
will just extract the empty frame. But
best record snippets
series - if this variable
will store the total number of frames.

ZXA_PAGE. It specifies the number
memory page, which is located
animation. This variable exists only
if ZXA_LARGE_ANIMATION = NO, because for
animations of a few fragments of it
is meaningless. Do not forget to bring back
page number, if your animation is
not at the bottom of memory!


   6.3 Playing multiple animations

 If you have a few animations, and you
want to play them all using the same
player, then you must perform several
conditions:
 1. As you can imagine, all of these animations
must be the same type as simultaneously
in ZXA library can only be used
one player.
 2. If this is normal or interlaced
animation, before playing each of the
them you will need to initialize
code of a player again, causing ZXA_INIT. This
necessary because size of the window frame to
each animation may be different. For C64
like animations, for which the frame sizes
are given directly in the code is not
help - for them it is necessary to size
frame at all animations were the same.
 3. If the animation consists of several
fragments - the frame size for each of the
They must be the same! This applies
all types of animations.
 How to ensure that the dimensions of frames in
different animations were the same - read
in the description of the packer.


              7. Conclusion

 Well that's all. I hope that this library
is useful to you in your programs. And
it does not need to be demos,
who prevents, say, draw transitions
between the levels of your game simple, but
cute animations.
 But I want to warn you about two things:
 1. Do not get involved in animation. They
You can vary your program, but
to rely only on animation is not worth it.
 Someone might accuse us that we
in part, of instigating the present fashion
the use of animation, and now, in
top of all released a library for
playing animations. Maybe so,
but that, when used skillfully gives
positive result can give and
quite the opposite result. If
we used the animation - meaning considered
it is necessary for the demos, and not because of
the fact that we do not have the strength to write another
a couple of effects. And if someone uses a
Deme animation just for the animations - the
it is not demomeyking.
 2. Do not forget that a compression algorithm for
which established the library was
specially designed for packaging strictly
one type of animation!
 I am not in any way claim to be
positioning of this algorithm as
universal. So you, by any
have to use it only for
animations, for which this algorithm was
originally intended. For quality
Packing all other types of animations I
not answer, indeed I am almost certain that
quality of packaging will be low. From
what I saw, to me personally on quality,
compression ratio and speed of most
liked VideoCruncher by Konex / ATS. But
unfortunately, its algorithm and / or source
Konex not configured (perhaps only for now)
make available to the public. So
between VideoCruncher'om and ZXA library is
One important difference in favor of the latter:
ZXA library is available in the
source code and full description. So
that while all the other authors of the steep
Player animations are shaken - you
have to use what is there.

 There is also the opinion of individuals that
distribution of the source would
to the emergence of the same heap, no one
not needed programs from different lamer not
able to write something of my own. On this
occasion I can only say one thing: lamer
simply not be able to use these (or
any other) sources, simply because
its level of development is not enough. But
a man more experienced the presence of such
source will save time and
force and will do no invention
bicycle, and sharpening the appearance of
its program.
 So that those who need it, can
to use one library for their
needs. Others can be seen on its example,
how you can create at full Speccy
library. Still others will perhaps find
something new or useful for myself in the code
library. In general many people it will be
useful, and at least for the sake of its worth
make and to publish.