comparison stitch/source.c @ 0:5242703e91d3 tip

Initial checkin for AIM92 aimR8.2 (last updated May 1997).

+/*
+	source.c
+	========
+
+	New super minimal source system.
+
+	John Holdsworth, 2nd January 1989.
+
+	edited: MAA 3-8-1993
+                new options "review_aid" and "frameno_aid"
+
+*/
+
+#if 0
+
+    What is a Source?
+    =================
+
+    Sources are a suggested style for coding  computational  processes  on
+    continuous data streams.  Making the extra effort to code according to
+    this style allows such processes to be easilly  cascaded  while  still
+    able to operate on data streams of indefinite length.  This is done by
+    performing the processing of the data stream in segments  and  passing
+    intermediate  results systematically between processing stages using a
+    simple convention.
+
+    A source is like a file, in that it specifies the source of stream  of
+    data.  The  data  can  be  read in segments of user-defined size, like
+    reading from a file.  For example, the routines  sread()  and  sseek()
+    operate  on  Sources  the same way that fread() and fseek() operate on
+    file streams. (sseek() operations on sources can only move forward  in
+    a data stream).
+
+    Sources are different from files in  that  they  do  not  necessarilly
+    just read data from disk. A Source may generally be a transformation
+    of data, or some simple processing operation on data. In addition, the
+    data may originate in any way the user may specify. The data may come
+    from a previous (cascaded) "Source".
+
+    The structured type "Source" contains enough information to generate
+    a stream of data. One way of processing a stream of data is to perform
+    a simple data-processing operation on another stream of data.
+    The input stream can be specified using a source.
+    Composite  data-processing  functions  can be built up by cascading a
+    number of elementary functions.
+
+    If  data  is  processed  in  large  enough  segments,  the overhead of
+    performing the processing task in stages is not significant.
+
+
+    How to use sources
+    ==================
+
+    There are two distinct phases in working with sources, analogous to
+    opening a file (eg fopen()), and reading the file (eg fread()).
+
+    The first phase uses "setup" functions, analogous to fopen().
+    (See io.c for sources which read from disk. See model.c for sources
+    which perform specialised auditory-modelling processes).
+    Setup functions always return a Source. They may take one or more
+    sources as arguments, as a specification of the input to the process
+    the source performs. The user may define his own setup routine for
+    any new process. This routine intialises the source structure with
+    a pointer to a callback function, which performs the data processing
+    when the source is used.
+
+    The second phase uses pull/fill/roll functions, analogous to fread().
+    Unlike the fread function, Sources do not require  you  to  supply  a
+    buffer  for  the  data to be "read" into.
+    There are three types of operation that can be  performed  on  sources
+    depending on whether the users wishes to supply the data buffer.
+    (These three operations are referred to as "methods", in the style of
+    object-oriented programming. Sources are thought of as "objects").
+
+    The Pull() method returns  a  pointer  to  a  buffer which has been
+    allocated  by  the  source itself.
+    In the following example, the buffer will contain the next 100 bytes
+    of processed data.
+
+	/* declarations */
+	char     *buffer ;
+	Source    source = OpenSource( somehow ) ;
+	ByteCount bytes  = 100 ;
+
+	/* call to "pull" 100 bytes of data out of Source "source" */
+	buffer = Pull( source, bytes ) ;
+
+
+    If the user has a buffer available for data and would prefer the  data
+    be directly tranfered into it, the Fill() method can be used instead of
+    the Pull() method.  The Fill method returns the address of the  buffer
+    the user provides in case it is of use for the programmer.
+
+	/* declarations */
+	char      buffer[100] ;
+	Source    source = OpenSource( somehow ) ;
+	ByteCount bytes  = 100 ;
+
+	/* call to "fill" the user's buffer with 100 bytes of data */
+	(void) Fill( source, bytes, buffer ) ;
+
+
+    In addition there is one further method of calling data from a  source
+    that  works like Pull(), but keeps a given number of bytes from the
+    previous call in the buffer.
+    The pointer returned by roll points to the start of the new data, as
+    in pull, but the space immediately before the pointer is still valid
+    and contains a specified number of bytes of data kept from the previous
+    call.
+    Bytes at the end of the buffer can be kept for the following roll call.
+
+	/* declarations */
+	char     *buffer ;
+	Source    source = OpenSource( somehow ) ;
+	ByteCount bytes  = 100 ;
+
+	/* call to "pull" 100 bytes of data out of Source "source"    */
+	buffer = Roll( source, bytes, 50 ) ;
+
+	/* "pull" another 100 bytes out of the source.                */
+	/* The last 50 bytes of the previous call will be kept in the */
+	/* buffer, and will immediately precede the new 100 bytes.    */
+	buffer = Roll( source, &bytes, 50 ) ;
+
+
+    In order for Roll to work properly though it MUST be  the  only  call
+    made  on  a  given  source.  This  is  as  it retains more information
+    between calls than the Pull() and Fill() methods.
+
+
+    More recent versions are defined as: PullSome, FillSome, RollSome.
+    In these methods, a pointer to the number of bytes (eg. &bytes) is
+    used, so that the source can indicate that less data was available
+    than was requested.
+
+    Remember also that requesting a negative number of bytes is interpreted
+    as requesting a skip without processing of the negative of that number
+    of bytes. This works as most processing sources will simply ignore
+    a request to process a negative number of bytes but will pass on the
+    request to their input sources which may which to actually act on the
+    skip operation.
+
+    More importantly A request for zero bytes it taken to mean that the
+    source is not required anymore and should close itself and free any
+    resources it is using. If the request is passed on to any input sources
+    a close operation cascades the close request to it's' input sources. This
+    means in order to close a cascade of process only the final source need be closed.
+    N.B. The close operation is only performed if the number of bytes requested is
+    zero not if the number of bytes returned is zero.
+
+
+
+...ctd jwh
+
+    Writing new sources
+    ===================
+
+    At the lowest level a source is a pointer to a struct which contains
+    pointers to three functions or methods to deal with the three types
+    of request that can be issued to a source. Pull(), Fill(),and Roll()
+    are #defines macros that convert the not quite C language calls into
+    full C calls passing the source pointer as the first argument then
+    the arguments the user specifies.
+
+    For example:
+
+	buffer = PullSome( source, bytes ) ;
+
+    Becomes:
+
+	buffer = source->methods->pull( source, bytes ) ;
+
+    The #define macros is used simply as a convienience.
+
+    The basic Source typedefs are as follows :
+
+    typedef struct _methods {
+	Pointer (*pull)(), (*fill)(), (*roll)() ;
+      } Methods ;
+    typedef struct _source  {
+	Methods methods ; Pointer buffer ; ByteCount bsize, valid ;
+      } Source ;
+
+    All sources must point to a structure containing at least this information
+    for Pull(), Fill() and Roll() operations to work on all sources.
+
+    To create a source the user initialises a static variable of type struct _methods with
+    the three routines written to support the three basic source operations.
+    A pointer to this structure is then used to initialise the methods field of
+    the struct _source section of the source's' state. A pointer to this structure
+    becomes the new source.
+
+    The function setSource() is provided to perform this minimal setup  of
+    a  new  source  and  to  initialise  the  other  fields  in the source
+    structure. The pointer to the new Source structure is allocated outside
+    setSource and passed to it in order to alow the possibility of it containing
+    more than the basic source information.
+
+#endif
+
+#include <stdio.h>           /* added: MAA 3-8-1993*/
+#include "stitch.h"
+#include "source.h"
+#include "options.h"         /* added: MAA 3-8-1993*/
+
+#ifndef DEBUG
+#define DEBUG 0
+#endif
+
+
+/*
+    initialise new Source structure
+
+*/
+
+Source setSource( source, puller, filler, roller, name )
+struct _source *source ;
+Pointer (*puller)(), (*filler)(), (*roller)() ;
+char *name ;
+{
+    Source returned ;
+    Source (*opener)() = 0 ;
+
+    source->pull    =  puller ;
+    source->fill    =  filler ;
+    source->roll    =  roller ;
+    source->open    =  opener ;
+
+    source->type    =  "void" ;
+    source->name    =   name  ;
+
+    source->opened   =           0 ;
+    source->returned = (Pointer) 0 ;
+#if DEBUG
+    printf( "Creating %s\n", SourceName( source ) ) ;
+#endif
+    _SPTR( returned ) = source ;
+
+    return ( returned ) ;
+}
+
+Source typeSource( source, type )
+Source source ;
+char *type ;
+{
+    _SPTR( source )->type = type ;
+
+    return ( source ) ;
+}
+
+char *sourceType( source )
+Source source ;
+{
+    return ( _SPTR( source )->type ) ;
+}
+
+char *sourceName( source )
+Source source ;
+{
+    return ( _SPTR( source )->name ) ;
+}
+
+Pointer deleteSource( source )
+Source source ;
+{
+#if DEBUG
+    printf( "Deleteing %s\n", SourceName( source ) ) ;
+#endif
+    Delete( source ) ;
+
+    return ( (Pointer) 0 ) ;
+}
+
+
+#if 00
+struct _source_operators NameOfClass = {
+ setSource, deleteSource,
+ typeSource, sourceType,
+ sourceName
+ } ;
+#endif
+
+
+/* MAA: 3-8-1993 */
+    
+void sinkSource( source, framebytes, frames )   
+Source source ;
+int framebytes ;
+long frames ;
+{
+    long frame ;
+    
+
+    extern *reviewstr;
+    extern *framenumberstr;
+
+    for( frame=0 ; frame<frames ; frame++ ) {
+
+      if ( isON (framenumberstr) || isON (reviewstr) ){
+	fprintf(stderr, " %i ", frame+1);
+	fflush(stderr);}
+
+      (void) Pull( source, framebytes ) ;
+
+      if ( isON (reviewstr)) {
+	fflush(stdin);getchar();}
+      }
+    return ; 
+}
+
+
+
+void CloseSource( source )
+Source source ;
+{
+    (void) Pull( source, 0 ) ;
+
+    return ;
+}
+
+void sinkAndCloseSource( source, framebytes, frames )
+Source source ;
+int framebytes ;
+long frames ;
+{
+    SinkSource( source, framebytes, frames ) ;
+
+    CloseSource( source ) ;
+
+    return ;
+}
+
+/* tapping derived source */
+
+typedef struct {
+    struct _source parent ;
+    Pointer state ;
+    void (*callback)(), (*close)() ;
+    Source input ;
+} *TappingSource ;
+
+static Pointer tapping_callback( source, bytes, buffer, last )
+TappingSource source ;
+ByteCount *bytes ;
+Pointer buffer ;
+int last ;
+{
+    source->callback( source->state, bytes, buffer, buffer+*bytes ) ;
+
+    if( !last )
+	return ( buffer ) ;
+    else {
+	if( source->close != (void ( * )()) 0 )
+	    source->close( source->state ) ;
+
+	return ( DeleteSource( source ) ) ;
+    }
+}
+
+static Pointer tappingPuller( source, bytes )
+TappingSource source ;
+ByteCount *bytes ;
+{
+    register int last = *bytes == 0 ;
+    Pointer buffer = PullSome( source->input, bytes ) ;
+
+#if DEBUG
+    printf( "\"%s\" pull tapping %d from \"%s\"\n", SourceName( source ), *bytes, SourceName( source->input ) ) ;
+#endif
+
+    return ( tapping_callback( source, bytes, buffer, last ) ) ;
+}
+
+static Pointer tappingFiller( source, bytes, buffer )
+TappingSource source ;
+ByteCount *bytes ;
+Pointer buffer ;
+{
+    register int last = *bytes == 0 ;
+
+    FillSome( source->input, bytes, buffer ) ;
+
+#if DEBUG
+    printf( "\"%s\" fill tapping %d from \"%s\"\n", SourceName( source ), *bytes, SourceName( source->input ) ) ;
+#endif
+
+    return ( tapping_callback( source, bytes, buffer, last ) ) ;
+}
+
+static Pointer tappingRoller( source, bytes, keep )
+TappingSource source ;
+ByteCount *bytes, keep ;
+{
+    register int last = *bytes == 0 ;
+    Pointer buffer = RollSome( source->input, bytes, keep ) ;
+
+#if DEBUG
+    printf( "\"%s\" roll tapping %d from \"%s\"\n", SourceName( source ), *bytes, SourceName( source->input ) ) ;
+#endif
+
+    return ( tapping_callback( source, bytes, buffer, last ) ) ;
+}
+
+Source newTappingSource( state, callback, close, input, name )
+Pointer state ;
+void (*callback)(), (*close)() ;
+Source input ;
+char *name ;
+{
+    DeclareNew( TappingSource, source ) ;
+
+    source->state    = state    ;
+    source->callback = callback ;
+    source->close    = close    ;
+    source->input    = input    ;
+
+    return ( SetSource( source, tappingPuller, tappingFiller, tappingRoller, name ) ) ;
+}
+
+/* rollable derived source */
+
+typedef struct {
+    struct _source parent ;
+    Pointer buffer ;
+    ByteCount bsize, valid ;
+    Source input ;
+} *RollableSource ;
+
+Pointer DeleteRollableSource( source )
+RollableSource source ;
+{
+    if( source->bsize != 0 )
+	Delete( source->buffer ) ;
+
+    return ( DeleteSource( source ) ) ;
+}
+
+static Pointer rollablePuller( source, bytes )
+RollableSource source ;
+ByteCount *bytes ;
+{
+#if DEBUG
+    printf( "rollable \"%s\" pulling %d from \"%s\"\n", SourceName( source ), *bytes, SourceName( source->input ) ) ;
+#endif
+
+    return ( RollSome( source->input, bytes, 0 ) ) ;
+}
+
+static Pointer rollableFiller( source, bytes, buffer )
+RollableSource source ;
+ByteCount *bytes ;
+Pointer buffer ;
+{
+    register int last = *bytes == 0 ;
+
+    FillSome( source->input, bytes, buffer ) ;
+
+    source->valid = *bytes ;
+
+#if DEBUG
+    printf( "rollable \"%s\" filling %d from \"%s\"\n", SourceName( source ), *bytes, SourceName( source->input ) ) ;
+#endif
+
+    if( !last )
+	return ( buffer ) ;
+    else
+	return ( DeleteRollableSource( source ) ) ;
+}
+
+static Pointer rollableRoller( source, bytes, keep )
+RollableSource source ;
+ByteCount *bytes, keep ;
+{
+    register int last = *bytes == 0 ;
+    Pointer oldBuffer = source->buffer ;
+    ByteCount toStore = *bytes + keep ;
+
+    if( source->bsize < toStore ) {
+
+	source->buffer = Allocate( toStore, "source.c for retaining buffer" ) ;
+
+	source->bsize = toStore ;
+    }
+
+    if( oldBuffer == (Pointer) 0 )
+	ZeroArray( (char *) source->buffer, keep ) ;
+    else {
+	CopyArray( (char *) oldBuffer+source->valid-keep, (char *) source->buffer, keep ) ;
+
+	if( oldBuffer != source->buffer )
+	    Delete( oldBuffer ) ;
+    }
+
+    FillSome( source->input, bytes, source->buffer + keep ) ;
+
+    source->valid = keep + *bytes ;
+
+    if( !last )
+	return ( source->buffer + keep ) ;
+    else
+	return ( DeleteRollableSource( source ) ) ;
+}
+
+Source newRollableSource( input )
+Source input ;
+{
+    DeclareNew( RollableSource, source ) ;
+
+    source->buffer = (Pointer) 0 ;
+
+    source->bsize =   0   ;
+    source->valid =   0   ;
+
+    source->input = input ;
+
+    return ( SetSource( source, rollablePuller, rollableFiller, rollableRoller, "rollable" ) ) ;
+}
+
+/* all other sources don't support rolling */
+
+Pointer nonRoller( source, bytes, keep )
+Source source ;
+ByteCount *bytes, keep ;
+{
+    stitch_error( "Sorry rolling not availiable on source \"%s\"\n", SourceName( source ) ) ;
+
+    return ( Pull( source, bytes ) ) ;
+}
+
+
+
+/* for compatability */
+
+typedef struct _auto_source {
+    struct _fillable_source parent ; Pointer state ; void (*callback)() ;
+  } *AutoSource ;
+
+static Pointer autoFiller( source, bytes, buffer )
+AutoSource source ;
+ByteCount *bytes ;
+Pointer buffer ;
+{
+    register int last = *bytes == 0 ;
+
+    source->callback( source->state, *bytes, buffer ) ;
+
+    if( !last )
+	return ( buffer ) ;
+    else
+	return ( DeleteFillableSource( source ) ) ;
+}
+
+Source stdAutoSource( state, callback )
+Pointer state ;
+void (*callback)() ;
+{
+    DeclareNew( AutoSource, source ) ;
+
+    source->state    = state    ;
+    source->callback = callback ;
+
+    return ( SetFillableSource( source, autoFiller, "stdAuto" ) ) ;
+}
+
+typedef struct _self_source {
+ struct _pullable_source parent ; Pointer state, (*callback)() ;
+ } *SelfSource ;
+
+static Pointer selfGenerator( source, bytes )
+SelfSource source ;
+ByteCount *bytes ;
+{
+    register int last = *bytes == 0 ;
+    Pointer ptr = source->callback( source->state, *bytes ) ;
+
+    if( !last )
+	return ( ptr ) ;
+    else
+	return ( DeleteSource( source ) ) ;
+}
+
+Source stdSelfSource( state, callback )
+Pointer state ;
+Pointer (*callback)() ;
+{
+    DeclareNew( SelfSource, source ) ;
+
+    source->state    = state    ;
+    source->callback = callback ;
+
+    return ( SetPullableSource( source, selfGenerator, "stdSelf" ) ) ;
+}
+
+Source stdStaticSource( ptr )
+Pointer ptr ;
+{
+    return ( NewStaticSource( ptr ) ) ;
+}
+
+Source stdSlaveSource( source )
+Source source ;
+{
+    return ( NewSlaveSource( source ) ) ;
+}
+
+Pointer oldPull( source, bytes )
+struct _source *source ;
+ByteCount bytes ;
+{
+    ByteCount tmp = bytes ;
+
+    return ( source->pull( source, &tmp ) ) ;
+}
+
+Pointer oldFill( source, bytes, buffer )
+struct _source *source ;
+ByteCount bytes ;
+Pointer buffer ;
+{
+    ByteCount tmp = bytes ;
+    Pointer bptr = buffer ;
+
+    do {
+	tmp = buffer + bytes - bptr ;
+
+	source->fill( source, &tmp, bptr ) ;
+	bptr += tmp ;
+
+    } while( bptr < buffer + bytes && tmp != 0 ) ;
+
+    return ( buffer ) ;
+}
+
+Pointer oldRoll( source, bytes, keep )
+struct _source *source ;
+ByteCount bytes, keep ;
+{
+    ByteCount tmp = bytes ;
+
+    return ( source->roll( source, &tmp, keep ) ) ;
+}
+
+#if 00
+static struct _source convertors = { oldPull, oldFill, oldRoll } ;
+struct _source *call_conversions = &convertors ;
+#endif
+
+/* for binding multiple sources */
+
+#if !defined(PC) && !defined(DSP32)
+#include <varargs.h>
+
+Source *BindSources( va_alist )
+va_dcl
+{
+    Source *inputs ;
+    va_list argp ;
+    int count, c ;
+
+    va_start( argp ) ;
+
+    for( count=0 ; _SPTR( va_arg( argp, Source ) ) != (struct _source *) 0 ; count++ )
+	;
+
+    inputs = NewArray( Source, count+1, "for binding inputs in source.c" ) ;
+
+    va_end(   argp ) ;
+    va_start( argp ) ;
+
+    for( c=0 ; c<=count ; c++ )
+	inputs[c] = va_arg( argp, Source ) ;
+
+    va_end(   argp ) ;
+
+    return ( inputs ) ;
+}
+#endif
+
+struct _source notRealySource ;
+
+Source EmptySource ;