Amazon
Isis software documentation
Amazon
Amazon is a library of Isis objects for handling complex
compositions of images and video. Using this version of Amazon, you
can manipulate visual media "actors" in a two-dimensional window
area which will be rendered on an output device such as an X window or
an external monitor.
Four kinds of objects can be instantiated and manipulated:
- Sources represent actual image data that will be combined
and rendered. Sources may retrieve image data from JPEG or GIF images
from URLs, Isis movies, and Isis image buffers.
- Actors represent the individual media objects that will be
combined for output. Each Amazon actor contains information about
how the image data will be rendered (like its position, scale,
and transparency factor) and a reference to an Amazon source which
represents the actual image data that will be rendered.
- Engines represent the "processors" that perform a
composition of actors into an output window. Each engine contains a
reference to a window and a list of actors to render in that window.
- Windows represent a location to which an engine can render
images. This version of Amazon supports windows that refer to X
windows, MME external displays, and image buffers.
Each instantiated object contains parameters that control its state
which are initially set to intuitive default values. Some of these
parameters will contain references to other objects in the system,
allowing a complex web to be constructed. For example, an engine has
a reference to an output window and to a list of actors that will be
rendered there. Actors contain references to media sources that
contain the actual image data that will be rendered.
All media and device interaction is controlled from within the
objects---all you have to do is create the web of connections between
the appropriate objects and write the script such that their
parameters are updated to appropriate settings depending on the values
of timers, sensors, user identity, or whatever other factors. The
current configuration may be "realized" to the output devices at any
point.
Several webs, each containing its own engine, window, etc., may be
created and used at the same time, and single objects may be
referenced multiple times if desired. For example, a single media
source may be referenced by several different actors, or a single window
may serve as the output destination for more than one engine.
Initializing the Amazon system
(load "amazon.isis")
You must load the script "amazon.isis" before using the
Amazon library.
Creating Amazon objects
Before writing your script, make a plan of the structure of the
individual media objects in your presentation and how they will be
combined. Then decide how you will represent this structure using
Amazon objects. If possible, start your script by creating all of the
Amazon objects you will need for the entire presentation.
(new-source-url) # create a URL image source - RGB
(new-source-url-yuv) # create a URL image source - YUV
(new-source-movie) # create an Isis movie source - RGB
(new-source-movie-yuv) # create an Isis movie source - YUV
(new-source-image-buffer) # create an IMAGE BUFFER source
(new-source-text) # create a PostScript TEXT source
(new-actor) # create new RGB actor
(new-actor-yuv) # create new YUV actor
(new-engine) # create new engine
(new-window-x) # create new window -- RGB X window display
(new-window-image-buffer) # create new window -- RGB image buffer
(new-window-image-buffer-yuv) # create new window -- YUV image buffer
(new-window-mme) # create new window -- MME RGB display
(new-window-mme-stream) # create new window -- Stream MME RGB display
(new-window-mme-yuv) # create new window -- MME YUV display
(new-window-mme-yuv-stream) # create new window -- Stream MME YUV display
You may instantiate as many of the four kinds of objects as you like
by calling the corresponding constructor (new-whatever). Be
sure to use only all RGB or all YUV objects. YUV objects will work
faster than RGB objects on MME window (external monitor) displays, but
YUV objects will not work for X window output.
The constructor returns a procedure which serves as your interface to
that object. By passing different kinds of arguments to this
procedure, you operate on the object in different ways. Each object
accepts either commands or queries, as described below.
Commands take the form of lists in which the first item is an
"opcode" specifying which command to execute, and the rest of the
items are the arguments for that command. Several commands may be
passed in each call to the object, and they will be carried out in
order. Commands may also be passed when calling the constructor of
the object.
Queries do not take any particular action--they just return the
state of a particular aspect of the object. To perform a query, pass
a query code as the ONLY argument to the object and the result will be
returned.
The following sections explain the commands and queries that each kind
of object will accept.
Sources
Commands that work the same on any source:
[src-get srcref] # get specified frame or ref of source
# returns: [buf abuf ref hotpoint]
[src-destroy] # close files/free image buffers
The src-get command is used by Amazon actor objects, so you
will not have to use it directly except in extreme circumstances.
Given a reference (such as a frame number), this command will return a
list of 4 items: the image buffer, the alpha buffer (or Null if
nonexistent), the actual reference of the image, and the positioning
point (hotpoint) of the image.
The src-destroy command should be invoked on any source that
you do not intend to use again so that any associated image memory can
be released and file handles can be closed.
Commands specific to URL sources:
[src-url url] # set URL (retrieves image)
This command sets the URL that a URL source points to. The image is
retrieved immediately using whatever protocol necessary. JPEG and GIF
image types are supported. GIF animations are also supported, but
animations must be saved with frame optimization turned OFF.
Commands specific to Isis movie sources:
[src-movie movie-object] # set movie object (opened previously)
[src-usealpha usealpha-flag] # use alpha channel if present in movie
[src-mme mme mmesize mmejpegbuf # set decompression items
mmeyuvbuf mmergbbuf] # NOTE: omit mmergbbuf for YUV movie
The src-movie command sets the Isis movie object that the
source should point to. You can change the movie the source points to
at any time. Isis movie objects are opened using the
new-isis-movie function explained in the Isis movie documentation.
The src-usealpha command can be invoked with True or
False to enable access to an alpha channel if it exists.
The src-mme command should be invoked once right after
creating the movie source to set the decompression parameters of the
movie source. It expects an open MME decompression handle, a frame
size, and correctly-sized MME JPEG, YUV, and RGB buffers to use for
decompression.
Commands specific to image buffer sources:
[src-put buf abuf srcref hotpoint] # set all info
[src-buf buf] # set the image buffer
[src-abuf abuf] # set the alpha buffer
[src-ref srcref] # set the reference
[src-hotpoint hotpoint] # set the hotpoint
[src-yuv yuv-flag] # set the YUV flag (True if is YUV image)
These commands allow you to set the information needed by an image
buffer source, such as the actual Isis image buffer the source will
point to, an alpha buffer, the reference, the positioning point, and a
YUV True/False flag. See the image buffer
protocol documentation for more information on the format of Isis
image buffers.
Commands specific to text sources:
[src-handle ps-handle] # set postscript engine handle
[src-yuv yuv-flag] # set color space of text output
[src-height text-height] # set text height in pixels
[src-text text-string] # set actual text string
[src-font fontname] # set font name
[src-quality quality] # set quality (default = 3)
[src-color [r g b]] # set color (use [y u v] in YUV mode)
For more information on the meanings and ranges of the parameters
shown above, see the PostScript
text documentation. The Amazon text source uses
ps-best-text from that library to generate anti-aliased text.
You must initialize the PostScript engine yourself by calling
ps-init and passing the returned handle to the
src-handle command above before attempting to use the text
source (see examples).
yuv-flag defaults to False, meaning that RGB text
images will be generated. If set to True YUV output will be
generated. Be sure to match this mode with the kind of actor the
source will be attached to.
The src-color command sets the color of the text. The color
should be a list of 3 integers between 0 and 255. These three
integers will be interpreted as RGB or YUV values depending on the
setting of yuv-flag.
Queries that work on any source:
src-buf # returns the current image buffer
src-abuf # returns the current alpha buffer
src-ref # returns the current reference (frame number)
src-hotpoint # returns the current image hotpoint
src-size # returns the current image size
src-yuv # returns True if the image is YUV, False if RGB
Queries specific to certain kinds of sources:
src-movie # returns the Isis movie object of a movie source
src-mme # returns the mme decompression handle of a movie source
src-url # returns the URL of the image in a URL source
src-handle # returns postscript engine handle of a text source
src-height # returns text height
src-text # returns text string
src-font # returns text font name
src-quality # returns text quality factor
src-color # returns text color
Source Examples
The following code creates two URL sources, one that points to a GIF
image on the Web, and the other that points to a JPEG image in the
current directory. Note that the commands can be invoked after
creating the Amazon object, or in the call to the constructor.
(set facesrc (new-source-url))
(facesrc [src-url "http://www.ddb.com/olegv/hakon.gif"])
(set catsrc (new-source-url [src-url "file:cat.jpg"]))
The following code creates two YUV movie sources, each pointing to
different Isis movies. Be sure to used only YUV or RGB Amazon objects
throughout your script, whichever is appropriate. Note the MME
decompression initialization in the first 4 lines (see the MME video services documentation for more
information).
(set decomframesize [320 240]) # assumes movies are this size
(set mmedecom (mme-init-decompress mme-jpeg mme-yuv decomframesize))
(set jpegbuf (mme-create-buffer mme-jpeg decomframesize))
(set yuvbuf (mme-create-buffer mme-yuv decomframesize))
(mme-decompress-start mmedecom)
(set banjomovie (new-isis-movie "/mas/garden/isis/movies/banjoman"))
(set piratemovie (new-isis-movie "/mas/garden/isis/movies/piratewoman"))
(set banjosrc (new-source-movie-yuv))
(banjosrc [src-mme mmedecom decomframesize jpegbuf yuvbuf]
[src-movie banjomovie])
(set piratesrc (new-source-movie-yuv))
(piratesrc [src-mme mmedecom decomframesize jpegbuf yuvbuf]
[src-movie piratemovie])
The following code creates a text source. First the postscript engine
is initialized by calling ps-init (see the PostScript text documentation for more
info). The returned ps-handle is passed to the
src-handle command of the source. A height of 40 pixels and
yellowish color is chosen.
(set ps-handle (ps-init))
(set textsrc (new-source-text [src-handle ps-handle]
[src-height 40]
[src-text "Satyricon"]
[src-font "Helvetica"]
[src-color [240 140 50]]))
Actors
Commands:
[ac-source source] # source referred to by this actor
[ac-position [xpos ypos]] # position actor in 2d mode
[ac-scale scale] # set the scale, same x and y scale
[ac-scale [xscale yscale]] # set the scale, different x and y scales
[ac-visibility visibility] # set the visibility 0.0 to 1.0
[ac-srcref srcref] # set the source reference (frame number)
[ac-frame srcref] # same as ac-srcref
[ac-inkmode ac-ink-composite] # set for full alpha blending
[ac-inkmode ac-ink-transfer] # set for straight transfer
[ac-inkmode ac-ink-range botv topv] # set for range transfer
[ac-inkmode ac-ink-jpegalpha] # set for transparent jpeg images/movies
[ac-render outbuf] # render the actor into specified buffer
These commands operate on Amazon actors. The first 5 are the most
commonly used. ac-source allows you to assign the Amazon
source that the actor will retrieve images from. The
ac-position, ac-scale, and ac-visibility
commands set these parameters of the actor. Positions must be 2D,
scales may be a single real number or list of separate X and Y
direction scales, and the visibility should be a real number between
0.0 (transparent) and 1.0 (fully opaque).
The ac-srcref is exactly the same as the ac-frame
command. This command allows you to reference a particular image in a
source that may contain more than one image. If the source is a movie
or a GIF animation, you can select a specific frame number using this
command.
The ac-inkmode command allows you to control how the pixels
of the source are combined with the pixels in the output buffer.
There are four supported modes, each identified by the constants:
ac-ink-composite, ac-ink-transfer,
ac-ink-range, ac-ink-jpegalpha. Composite is the
default and performs full alpha blending. Transfer mode performs a
simple transfer of pixels, ignoring any transparency channel. Range
mode transfers only the pixels in a certain range that you select
(between 0 and 255). JPEG alpha mode is similar to range mode but is
used for JPEG movies or JPEG stills that have embedded transparency.
The ac-render command is only used by Amazon engines. When
invoked, the actor is rendered into the specified image buffer.
Queries:
ac-source # returns current Amazon source of the actor
ac-srcref # returns current source reference
ac-position # returns current position
ac-scale # returns current scale
ac-visibility # returns current visibility
ac-inkmode # returns current ink mode
Actor Examples
In the following code, three different actors are created. The
sources, positions, scales, and visibilities of each actor are
initialized. If any parameter is not initialized, an intuitive
default value is used. Note that the same source may be accessed by
more than one actor.
(set face (new-actor))
(face [ac-source facesrc]
[ac-position [100 100]]
[ac-scale 2.0]) # double size
(set cat1 (new-actor [ac-source catsrc]
[ac-position [50 145]]
[ac-visibility 0.75])) # 75 % opacity
(set cat2 (new-actor [ac-source catsrc] # same source as cat1
[ac-position [130 40]]
[ac-scale [1.0 0.75]] # will be a fat cat
[ac-visibility 0.68])) # 68 % opacity
The following example creates a YUV format actor, points it to a
Amazon movie source, and initializes its position and frame number.
(set starting-frame 60)
(set movie-position [160 120])
(set banjo (new-actor-yuv [ac-source banjomovie]
[ac-position movie-position]
[ac-frame starting-frame]))
Engines
Commands:
[eng-actors actor actor ...] # set actors referred to by engine
[eng-actor-list [actor actor ...]] # set actors referred to by engine
[eng-add-actors actor actor ...] # add specified actors
[eng-remove-actors actor actor ...] # remove specified actors
[eng-window window] # set window referred to by engine
[eng-reset] # remove window and all actors
[eng-clearmode clearmode] # set clearing to True or False
[eng-render] # render a frame to display
[eng-render-background] # render a frame to background store
The first four of these commands allow you to specify the list of
actors that the engine will render to the output window. The actors
are rendered in the order you specify them in these commands. If the
rendered actors overlap, those at the beginning of the list will
appear to be under those at the end of the list.
(eng-add-actors adds actors to the end of the actor list.)
The eng-window command sets the Amazon window to which the
engine will render its output. See the next section for information
on Amazon windows.
eng-reset removes all the actors and the window from the
engine.
The eng-clearmode command sets the clearing mode of the
engine. The default is True, meaning that the output buffer
is cleared before rendering the actors into it. If the clearing mode
is False, the output buffer will not be cleared and you will
see remnants of previous renderings in the output. This effect may
desirable in some cases. However, setting the clearing mode to
False may not work with all types of windows.
The two most important commands in an engine are eng-render
and eng-render-background. Invoking the eng-render
command causes all of the actors to be rendered and displayed to the
output window. To create animated output, you should call write your
script so that eng-render gets invoked repeatedly, with
changes made to actor parameters (position, scale, visibility, frame)
between each invokation.
eng-render-background works the same way as
eng-render, but it renders all of the actors into a special
background buffer instead of to the output display. This buffer is
used as the background image for all future calls to
eng-render. In other words, when the display buffer is
cleared before rendering the actors, it is cleared with this
background image. Therefore, if there is something in your
presentation that lies in the background and does not change from
frame to frame, you should render it into the background once using
eng-render-background at the beginning of the script.
Otherwise, this static component will have to be rendered again and
again, slowing down the performance of your system.
Queries:
eng-actors # returns current list of actors
eng-window # returns current window
eng-clearmode # returns current clearing mode
Engine Examples
The following code creates an engine with references to three actors
and a particular window (see next section for information about
windows). The render command is then invoked.
(set eng1 (new-engine))
(eng1 [eng-actors face cat1 cat2]
[eng-window win1])
(eng1 [eng-render])
Windows
Commands that work on any window:
[win-modify [x1 y1] [xsize ysize]] # mark a rectangle as "changed"
[win-modify [x1 y1 x2 y2]] # mark a rectangle as "changed"
[win-clear] # clear display buffer from background
[win-save] # save display buffer to background
[win-draw] # output display buffer
[win-destroy] # destroy window
You will not have to use these commands except in very extreme
situations. These commands are all used by an Amazon engine.
win-modify marks certain areas of the window's display buffer
as modified (as a result of actors being rendered) so that the window
can more intelligently control which parts of itself need to be
updated or cleared when the other commands are invoked.
The win-destroy command should be invoked when a window is no
longer needed so that any associated image memory can be released.
Commands specific to X windows:
[win-xwin xwin-handle] # set X window referred to by window
[win-maxsize [xsize ysize]] # change maximum size of window
[win-size [xsize ysize]] # change window size
[win-pos [xpos ypos]] # change window position
[win-title title-string] # change window title
These commands control aspects of an Amazon X window. The only two
that are required are win-xwin and win-maxsize.
win-xwin should be called to set the handle of the actual X
window that will be used for output, and win-maxsize should
be called to set the maximum size of that window (used for the
allocation of image memory). The others are used to change the size,
position and title of the X window. See the Isis X windows interface documentation for more
information on how to create an X window.
Commands specific to MME windows:
[win-mme mme-handle [xsize ysize]] # set MME handle referred to by window
This command should be called to set the handle and size of the MME
display that will be used for the output of an Amazon MME window. The
MME display should be initialized for the proper display type (RGB or
YUV) and size before invoking this command. See the MME video services documentation
for more information.
Commands specific to image buffer windows:
[win-buf fgbuf bgbuf] # set foreground/background image buffer
This command should be called to set the foreground and background
buffers to use for the output of an Amazon image buffer window. The
buffers should be the same size and of the proper type (RGB or YUV).
See the image buffer protocol
documentation for more information.
Queries:
win-buf # returns current foreground buffer of any window
win-bgbuf # returns current background buffer of any window
win-xwin # returns current handle of x window
win-maxsize # returns maximum size of x window
win-size # returns current size of x window
win-title # returns current title of x window
win-pos # returns current position of x window
win-mme # returns current mme handle of mme window
win-bgmmebuf # returns mme buffer used for background of mme window
Window Examples
The following creates an Amazon X window and initializes its
maximum size, title, and position.
(set framesize [300 300])
(set xwin (xwin-create Null Null Null framesize))
(set win1 (new-window-x [win-xwin xwin]
[win-maxsize framesize]
[win-title "My Amazon output"]
[win-pos [100 100]]))
The following creates a streaming YUV format MME window. Technically,
streaming windows are faster than non-streaming windows because
display operations are non-blocking. However, because they use
multiple buffers, setting the engine clearing mode to False
will not work with streaming MME windows.
(set framesize [320 240])
(set mme (mme-init-write-frame mme-yuv framesize))
(mme-stream-init mme)
(mme-stream-start mme)
(set win1 (new-window-mme-yuv-stream [win-mme mme framesize]))
The following creates an image buffer window and assigns two Isis
image buffers to act as the foreground and background for the window.
(set framesize [320 240])
(set foreground (new-standard-image 3 framesize))
(set background (new-standard-image 3 framesize))
(set win1 (new-window-image-buffer [win-buf foreground background]))
Full Examples
Example 1 is a very simple
full script that displays an image retrieved from a URL at the center
of an X window.
Example 2 is a more interesting
script in which a single actor is animated using timelines and timers.
Example 3 is an even more
interesting script in which a multiple actors are animated over a
background image.
Example 4 is a high-demand script
in which 3 overlapping movies are displayed over a background image. The
script utilizes YUV Amazon objects and MME window output.
Requirements:
Scripts:
| (load "amazon.isis")
|
Other:
| Needs all image, MME video, and X windows libraries
|