********************************************************************************
* $Source: /hell/dev/RCS/libio/README,v $
*
* Flame and Flint 4.0 framestore partition access API read-me.
*
* Last Modification: $Author: francois $
*                    $Revision: 1.6 $
*                    $Date: 1995/09/25 16:50:08 $
*
* Copyright (c) 1995 Discreet Logic Inc.
********************************************************************************


New Framestore Types Supported
------------------------------

'libio' now supports all types of framestores that are supported by
Flame and Flint 4.0:

         Stone & Wire framestore
         Logical Volume (LV) framestore
         Single disk (raw) framestore
         File (EFS Extent File System) framestore


'libio' Cooperation with Flame and Flint
----------------------------------------

'libio' works with both Flame and Flint.

At times Flame or Flint will lock out any attempt by 'libio' programs to
read or write to the framestore partition. The user of 'libio' functions is
responsible for checking the returned status to determine if a retry
(status 'LIBIO_RETRY') is required.

The version of the 'libio.so' library that one links against must be the one
that comes supplied in the "io" subdirectory of the currently used version of
Flame or Flint. Using a different version of the 'libio.so' library may cause
unexpected results, including corruption of the framestore.


Warning Regarding Minimizing Flame or Flint Into a Desktop Icon
---------------------------------------------------------------

As opposed to the behavior in previous versions, even if Flame or Flint
is running but minimized into a desktop icon, the other 'libio'
programs will be able to access (read and write) the framestore.


Permissions on 'libio' Programs
-------------------------------

Any program linked with the 'libio.so' library which accesses a framestore
partition must have sufficient privileges. Root privileges are required in
most cases:

   /bin/chown root <program pathname>
   /bin/chmod u+s  <program pathname>

This is a common cause of the failure of the 'ClipOpen' call.


AVAILABLE API
=============

There has been many changes to the 'libio' API since Flame 3.9.n and Flint 2.n.

The following functions are now available:

   'ClipOpen':          Opens an existing clip for read access
                        or creates a new clip.

   'ClipClose':         Closes an opened clip.

   'ClipReadFrame':     Reads a frame from an opened clip into a memory buffer.

   'ClipWriteFrame':    Writes a frame from a memory buffer into an opened clip.

   'ClipFramesFreeGet': Gets the number of free frames in a partition
                        and whether Flame or Flint is currently running
                        on this partition.

The clip info structure now contains the following useful fields:

   'clipLibPath': Clip library pathname.
   'clipName':    Clip name.
   'clipDate':    Clip creation date and time.

   'Width':       Partition frame width in pixels.
   'Height':      Partition frame height in pixels.
   'Depth':       Partition pixel depth in bytes.

   'Bytes':       Required frame buffer size in bytes.

   'Frames':      Duration of the clip in frames.

Detailed documentation can be found in file 'libio.h'.

Note that function 'ClipDeleteFrame' available in the Flame 3.9.11 'libio' API
is no longer available due to the new structure of the 4.0 clip libraries.


SAMPLE PROGRAMS
===============

There are a number of example source files demonstrating the use of
the 'libio' functions:

         rtest.c
         wtest.c
         ftest.c
         pttopt.c
         clipinfo.c


rtest.c	
-------

Opens the specified clip and displays it frame by frame in a window.

   rtest "<clip library pathname>@<clip name>[@<creation date&time>]" \
         [<starting frame number> [<ending frame number>]]


wtest.c
-------

Creates the specified clip from a sequence of SGI image files.

   wtest "<clip library pathname>@<clip name>" \
         <directory pathname>/<image file template> \
         [<starting image number> [<ending image number>]]


ftest.c
-------

Determines the number of free frames in a partition.

   ftest <clip directory pathname>/<framestore name>/<partition name>


pttopt.c
--------

Directly copies clip frames from one partition to another one.

   pttopt "<source clip library pathname>@<clip name>[@<creation date&time>]" \
          "<destination clip library pathname>@<clip name>" \
          [<source starting frame number> [<source ending frame number>]]

Demonstrates multiple framestore partitions access.
If the partitions differ in size, the frames are cropped or centered.


clipinfo.c
----------

Prints the contents of the 'ClipInfoStruct' associated with a clip.

   clipinfo "<clip library pathname>@<clip name>[@<creation date&time>]"

