Chapter 1 - Introduction and Overview

This documentation is intended to be read in order, but it is organized so that a more seasoned user can dip into it for reference.

Conventions:

Source listings are shown in
grey typewriter style like this.
For each section, important details are shown in bold for recognition.

Development Environment

In order to do this stuff, you should at least know C and have a passing acquaintance with make. Knowing C++ will help. You need the CC (C++) compiler and smake, a version of make shipped with SGI computers. If you are working on SGI, the standard SGI CC compiler or the GNU gcc compiler will both work.

For NT, visual C++ is required, or any compiler that will generate .dll files. The NT nmake will work on the supplied makefiles.

Image Formats

Chalice is an image-based tool, with a data-flow model. This means that data, in the form of framebuffers, are passed from node to node. Each node takes in one or more frames of information, and processes them, based on
  1. the node's core function,
  2. parameters set in the node's UI tabs, and
  3. the current frame (or current time).
A frame, or image, consists of the following:
  • X, Y resolution, in pixels
  • C, a number of channels (where a channel is red, green, etc)
  • a type, one of 8bit, 16bit or float (32 bits) per channel
  • other information, such as whether or not the image is shared, who created it, etc.
  • a pointer to a block of contiguous memory big enough to hold X * Y * C pixels
  • Exactly how this information is stored is described in chapter 5.

    How Nodes Work

    Plugin nodes are compiled as .so (shared object) files. Chalice loads all of these that it sees in the CHALICE_PLUGINS_PATH directory. These then become part of the menu that the user sees.

    When the user chooses a node and places it onto the Chalice workspace, two copies of the node are created: one runs in the UI process, taking values from the user via the user interface tabs that all nodes have, and the other runs in the work process, which does the actual image processing (recall that Chalice is actually always running two processes, a front process to interact with the user and a back one to do the work).

    Thus for each instance of the node on the workspace, there will be an instance running the user interface process. But there is only one copy of the node in the work process area. This copy will be executed at each invocation of the node.

    Warning:
    Chalice does not police the user's use of memory, pointers or other resources in plugins. It is very possible to write plugins that run amok in memory or on disk. It is the plugin writer's responsibility to write well-behaved code.

    What Happens When a Plugin Executes

    There are a series of routines that Chalice calls when a plugin executes; some of these are Chalice routines which the programmer can use (cpi functions) and the rest are routines which the programmer defines and Chalice expects to execute (upi). The upi routines are all optional, and have sensible default executions. They are called by Chalice as follows:

    The following functions are called once, when Chalice starts up (actually, they are called twice, once by Chalice, once by the work process). They are called in the order given, and then never called again:
    upiInitialize
    upiPluginType
    upiAuthorName
    upiPluginName
    upiCopyrightNotice
    upiPluginVersion
    upiCreateParameters
    upiNumberOfInputs

    Then, the following sequence of upi functions get called during the cooking process:
    upiOutputContext
    upiCheckInputSize
    upiCheckInputDepth
    upiRegionsNeeded
    upiCookFull
    upiResultInput
    upiRegionsNeeded
    upiProcessImage

    They get called in that order (though upiOutputContext can get called a few more times). Also note that upiRegionsNeeded is called twice. The first time is used to figure out the caching situation (i.e. figure out how many times an image is used, etc...). The second time it is used to actually do the cook.
    It is also worth saying that upiOutputContext is called many times within the execution of a single plugin, so it should be efficient.

    These functions get called whenever something changes:
    upiInputChanged
    upiParameterChanged
    upiNodeCreated
    upiNodeDeleted
    upiNameChanged

    These get called when the user wants some information:
    upiMessageInfo
    upiInputLabel
    upiOutputLabel


    [Previous Page] [Next Page]
    [Table of Contents] [Index]

    Copyright © 1998 Silicon Grail Inc.
    710 Seward Street, Hollywood, CA 90038