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.

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).

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.

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.

The following example creates a YUV format actor, points it to a Amazon movie source, and initializes its position and frame number.

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.

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.

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.

The following creates an image buffer window and assigns two Isis image buffers to act as the foreground and background for the window.

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

Scripts:	`(load "amazon.isis")`
Other:	`Needs all image, MME video, and X windows libraries`