ShowTime Users's Guide ShowTime is a program which rapidly reads and displayed images from files. ShowTime can be used interactively to display single images or single movies, or it can be used with a script file which contains commands. ShowTime reports its messages (such as error messages) to a log file. The log file is only created if ShowTime has a message to report. The file is typically created in the current working directory, and is called "showtime.log". If the log file can not be created, then ShowTime stops, and attempts to write a message to stderr explaining that it could not open the log file. Also, the message that was attempted to be displayed is also written to stderr, if possible. To run ShowTime, call it by its name. Here is the syntax of its usage: showtime [-f] [script-file] [options ...] where can be any of the following: -n : set the saturation scale factor. See :ntsc -c : force loading CGA color palette into first 16 indices At present there is no way to turn this off once it has been turned on from the command line. -s : set the inter-image delay. See :pause This is the amount of time delayed between each image, in seconds. can be any floating point value. -w [] : set the prefered window size in pixels. The display window is set to a size greater than or equal to the size requested by the user, if the hardware supports such a window. If the argument is provided, but the argument is omitted, then a value for the height is chosen such that the window, as closely as possible, has the aspect ratio of an NTSC television screen, which is the same as the old-style standard movie screen, which is 4:3. Here is a description of all of the ShowTime commands: :palette [filename] [:rgb332] [:gray] Load a palette from a PPM file. Normally PPM files contain images, but in this usage, the PPM file is used simply as an ordered list of palette entries. The order of the color pixels in the PPM file determine the order of the palette entries for the new palette. Palettes are also loaded automatically if they are included inside of PIC or CLP files. If the argument is omitted, the file "palette.ppm" is assumed. If the string ":rgb332" is in the place of a , then a palette is created and loaded where the 3 most significant bits are used for red, the next 3 for green, and the least 2 significant bits for blue. This is a common colormap scheme used for full color images. When a PPM image is loaded as an image (as opposed to loaded as a colormap) the red, green, and blue bits are loaded in the RGB332 format. If the string ":gray" is in the place of a , then a linear graymap is created and loaded as the palette. Any colormaps loaded are resaturated as dictated by the most recent ":ntsc" command. The default is to leave the saturation the same. :offset [x [y]] Offset the image horizontally from the left by pixels and vertically from the top by pixels. The offset remains in effect for each image displayed until another offset command is executed. :scale [x [y]] Scale the image by a factor of in the horizontal direction, and by a factor of in the vertical direction. The scale factors can be any floating point value. If the scale factor is a negative integer, then its positive reciprocal is used in scaling. Using a negative integer can be somewhat faster than using a floating point value smaller than 1.0. :pause [delay] Pause for seconds, then resume. The argument can be any floating point value. If is a negative value, then a special behaviour occurs: The ":pause" command waits for _at_most_ seconds, or until a key is pressed. :clear [bg] Clear the screen to the background color. If is supplied, it is used as the index in the colormap to clear the screen, otherwize 0 is assumed, which is black in the CGA palette. :open [filename [n]] Open the file named as file number . If the argument is omitted, then 0 (zero) is assumed. can be any integer between 0 and 10, inclusive. :close [n] Close the file . If is ommited, file 0 (zero) is closed. :next [n] Load and dislpay the next image from the previously ":open"'d file . If is omitted then 0 (zero) is assumed. The image can be any of the formats recognized by ShowTime. The image is transformed according to the current settings of :offset, :scale, and the current :xform. :load [n] Load the next image from the previously ":open"'d file If is omitted, then 0 (zero) is assumed. The image can be any of the formats recognized by ShowTime. The image is not displayed, but simply loaded into an internal buffer. The image is transformed according to the current :xform. :echo Display a text string. :frame Display the frame number at the current :offset location :author Load the ShowTime title screen into the internal image buffer. This is the image shown when the program is initially run. The image is not displayed, but simply loaded into an internal buffer. Also, a brief message describing the version and author of ShowTime is written to the log file. :repeat Display the image currently loaded into the image buffer. The image is displayed with the current settings of the :offset and :scale command. :show Same as the :repeat command. :vflip Flip the image vertically inside the image buffer. This does not display the image, but simply tells ShowTime to display the image vertically flipped. :hflip Flip the image horizontally inside the image buffer. This does not display the image, but simply tells ShowTime to display the image horizontally flipped. :ntsc [sat] Set the saturation scale factor to . This effects the next loaded palette. New palettes are resaturated according to the value. can be any floating poing value, but keep in mind that the only valid saturations are between 0.0 and 1.0 inclusive. This command is useful in desaturating fully saturated palettes, so that they can be displayed (and recorded) in NTSC format, which does not allow for chromanances saturated beyond 70%. Therefore, a good and typical value for for displaying in NTSC would be 0.7. :rem [text] Remark. Any following a :rem command is ignored by ShowTime, so it can be used to comment a ShowTime script for human readers. :xform Begin recording the image transformation script. All commands between :xform and :endxform are recorded into the image transformation. The image transformation is applied to every image loaded. Only some ShowTime commands are allowed to be present in an image transformation script. Image transformations can not be recursive. Since the transformation is executed upon loading the image and not upon displaying it, the :next command, if it appears in the image transformation, will not cause an execution of the image transformation. This allows tricks like displaying several simultaneous movies from separate files, if used in conjunction with the arguments to the :next and related image file commands. :endxform Stop recording the image transformation. See ":xform". :exit End the ShowTime program script. All text following this command is ignored by ShowTime. :rapid Read and display all of the images from the file named . This ignores keyboard and mouse events, and does not use one of the 0-10 indexed files, but the image xforms are still performed. :resume Resume playback mode. This command will put ShowTime back into the mode where single keypresses (or mouse button presses) control the playback of movie files. :forward Set the playback direction to forward. :reverse Set the playback direction to reverse. Load and display the images in the file named . As each image is loaded, the :xform script is executed, and each image is displayed in succession. Also, the current settings of :offset and :scale are applied to each image in as they are displayed. If the image tranformation defined with :xform includes the :next command with a file number argument (), and the file is open and contains images, then images from file are loaded and displayed simultaneously with the images from . This is a good way to display multiple movies simultaneously. Playback Mode: While ShowTime is playing a movie file, ShowTime will accept keyboard and mouse button presses to control the playback of the movie file: Keyboard: ' ' Pause, or if already paused, step one frame. 'p' 'P' 'CR' Resume continuous playback. ':' 'c' 'C' Accept the next command in the script or from input. ',' 'r' Set playback direction to "reverse" or step back one frame. '<' 'R' Set playback direction to "reverse" or play previous file. '.' 'f' Set playback direction to "forward" or step forward one frame. '>' 'F' Set playback direction to "forward" or play next file. 'q' 'Q' 'ESC' Stop ShowTime and exit. Mouse buttons (in versions with mouse support): 1 Set playback direction to "reverse" or step back one frame. 2 Pause, or if already paused, resume continuous playback. 3 Set playback direction to "forward" or step forward one frame. Image File Formats: ShowTime can recognize multiple image file formats automatically. To understand how images are loaded, it is important to understand the way they are displayed: All images displayed in ShowTime are "color mapped" which means that each pixel in the image is an integer refering to an index in a color lookup table, or palette, which determines what color the pixel will be. The palette is logically separate from the image in that multiple images may share the same palette. In fact, it is desirable to have multiple images share the same palette so that the palette does not have to be loaded from disk for each image. Palette files also come in different formats. Some image formats include the palette with the image. Some image formats have a separate palette file. Some image formats are "true color", which means that they do not have a palette at all, but store the whole color value for each pixel. ShowTime treats true color images in a special way, which still forces the use of a palette. Here is a description of various image file formats supported by ShowTime, and the ways they would be typically used: Targa image/palette: TrueVision Targa files use a versatile image format which can be either uncompressed or RLE compressed; can be colormapped, true color, or grayscale; can be vertically inverted; can be interlaced using 1, 2 or 4 fields per frame; can be offset from the origin; can install the colormap starting at an index other than the first; and other features. Targa's can contain their own colormap, which can be either an 8-bit or 16-bit colormap. Of these, only 8-bit colormaps are supported by ShowTime. However, the full-color Targas (15, 16, 24, or 32 bit) are supported by ShowTime with the RGB332 approximation. (See ":palette :rgb332" for more information about RGB332.) Monochrome (i.e. grayscale) Targa's can be used as PGM images, which means that the gray values can either be taken as gray values (which implies pre-loading a linear gray palette using ":palette :gray"), or they can be used as indices into a colormap. This can be used in conjunction with another, preceeding, Targa image which contains its own colormap which the following "monochrome" (actually colormapped) Targa's will use without having to carry their own colormap. The Targa RLE compression scheme is a simple one, and its compression ratios are typically comparable to that of the PIC image file format. However, Targa's compression is considerably faster in decompression, so playback of compressed Targa's will be significantly faster than playback of PIC files. Playback speeds of uncompressed Targa files are comparable to PGM and PPM files (depending on whether the Targa is monochrome or true color). (Note: Targa's can be automatically detected by ShowTime under most circumstances, but since Targa files lack a "magic number" there is never a guarentee that ShowTime could mistake a file using another format for a Targa. However, in these situations, the file format would not likely be one that ShowTime supports, and in any case the worst that can happen is that ShowTime will display garbage and the symptoms will be obvious.) PGM image: PGM, or Portable Gray Map, is a very plain grayscale image format that uses no compression and a simple ASCII header. PGM files were originally intended to be a portable way of storing and transfering gray images, but ShowTime uses them in a different way: Each pixel value in a gray image is represented by a single integer. This makes PGM files ideal for representing colormapped images since colormapped images also use a single integer to represent each pixel. The difference is that for grayscale images, that integer referes to the pixel's luminance, whereas in colormapped images, the integer refers to an index in the colormap (or palette). Therefore, when ShowTime displays a PGM image, it displays it with the current colormap. If the PGM image actually is a grayscale image (instead of a colormapped image) then ShowTime can display it correctly if the palette contains a linear grayscale map. To set the palette to a linear grayscale map, use the command ":palette :gray". PGM files come in 2 varieties: ASCII or Raw. ShowTime can read only the Raw form, since that is the faster and more common format. PPM image: PPM, or Portable Pixel Map, is a very plain true color image format that uses no compression and a simple ASCII header. Since PPM images are true color, they can not be completely represented by ShowTime. Instead, ShowTime loades the PPM in one of 2 ways, to approximate the full color PPM image: ShowTime can either dither the PPM image using a truncated RGB colormap, or ShowTime can convert the PPM image into a grayscale image by converting the colors into their corresponding luminance values (like the way a TV works when you turn the "color" knob all the way down so that the image is black and white). Kep in mind that either of these true color approximations depends on the correct palette having been loaded in advance for the image to appear correct. To load the palette with the truncated RGB colormap, use the command ":palette :rgb332". To load the palette with the linear grayscale map, use the command ":palette :gray". PPM files come in 2 varieties: ASCII or Raw. ShowTime can read either of these formats. PPM palette: The PPM palette is a special, nontraditional use of the PPM format. Since the PPM image format is so simple, and since there is an ASCII version of the PPM, which ShowTime can read, PPM files make excellent colormap files, by using a few restrictions: Normally a PPM file can have any dimensions, since they describe a rectangular image, but a colormap is a one-dimensional vector of RGB color triples. To use the the PPM file format as a palette, the dimensions of the PPM are ignored, and instead, the colors present in the PPM are used, in order, to fill the colormap (or palette). All pixels after the 256th are ignore, since the palette can have only 256 entries. To use a PPM file as a palette, use the command ":palette " PIC image/palette: The PIC image file format is an escaped-run length encoded (compressed) colormapped image file format. These images can contain their own colormaps, or the colormap can be omitted. If the colormap is present, ShowTime automatically loads it, which means that the ":palette" command is not necessary for viewing PIC images. However, if you want to load a PIC colormap without also loading its image, you can use the ":palette" command. If a PIC image does not contain a colormap, the image is displayed using the current colormap. Image File Concatenation: In order to keep the number of files in a movie down to a tollerable number, ShowTime allows for files which are simple concatenations of image files. That is, if you have a sequence of image files in a movie, you can copy them head-to-tail (with no stray bytes in between images) and ShowTime will read the entire file of images. This is particularly useful for MS-DOS machines, which slow to a crawl if the number of files in a directory is larger than about 100. In any case, it makes organizing movies simpler. Adding Image File Types to ShowTime: All image files are handled in a specific, modular way in ShowTime, so it is easy to add to the image file formats that ShowTime can handle. There are 2 components to any image format ShowTime can handle: A header, and the image body. For each image format, write one routine to load the header, and another to load the image body. The function prototypes for each of these routines and the required behaviours is always the same. The image header loading routine must set the number of rows and columns in the image body, as well as setting a pointer to the routine which loads in the image body. ShowTime must be able to automatically determine which image file format any image is by reading its header, so the image header loading routine must return a nonzero number if the image header routine did not find the image file to be correct for that type. If the image header routine determines that a file is not of the type it knows about, then the routine should fseek to rewind the file so that subsequent image file loaders can have the image stream from the beginning. After the image loading routines are written, put them together into one file, include the "image.h" and "showtime.h" files at the top along with whatever other files are "#include"'d, and create a header file to describe their prototypes. Then, edit the "image.c" file. Add a "#include" statement near the top to include the new module's header file. Then change the "load_header" routine to call the new image header loading routine. Follow the way other image file formats' headers are loaded. The "load_image" routine will not have to be changed, since the image header loading routine will set a pointer to the routine to load the image body. However, make sure the prototype of the image body loading routine conforms exactly to the prototype for image body loaders. See the "image.h" file for the prototype, and see the "pbm.c" and "pbm.h" files for examples of image header loaders and image body loaders. Recompile Showtime. After ShowTime has been recompiled, the new image format will be handled automatically. That is, in order to have ShowTime use the new image handling routines, simple tell it to read a file of the new type. Since the image header routine tells ShowTime whether or not a given file is of a particular type, ShowTime will automatically use the appropriate image file loading routines.