home *** CD-ROM | disk | FTP | other *** search
/ Openstep 4.2 (Developer) / Openstep Developer 4.2.iso / NextLibrary / Frameworks / NEXTIME.framework / Versions / A / Headers / NTSampleProcessorProtocol.h < prev    next >
Encoding:
Text File  |  1995-08-30  |  8.0 KB  |  200 lines
  1. /*
  2.  *  NTSampleProcessorProtocol.h
  3.  *     Copyright 1994, NeXT Computer, Inc.
  4.  *    
  5.  *    A set of protocols defining expected API in components used to
  6.  *    manipulate samples.
  7.  *
  8.  *    13 Jan 1994 mpaque Created.
  9.  */
  10. #import <Foundation/NSObject.h>
  11. #import <Foundation/NSDictionary.h>
  12. #import <Foundation/NSArray.h>
  13. #import "NTSampleBuffer.h"
  14.  
  15. /*
  16.  * NTConfiguration protocol: specifies how a sample processor
  17.  * is to be configured, and how it reports it's configuration and
  18.  * capabilities.
  19.  *
  20.  * Configuration for Sample Processors:
  21.  *
  22.  *
  23.  * Each sample processor works on samples of a given media type (i.e. Audio
  24.  * or Video).  Within each media type, there sample format types 
  25.  * (i.e. Compressed, or Raw) and format subtypes. (i.e. Cinepak
  26.  * Compressed, etc.).  A Sample processor typically contains an input
  27.  * port and an output port, each of which can be configured with a sample
  28.  * format type and subtype.  The format type and subtypes supported by
  29.  * a component are assumed to static properties. A complete format 
  30.  * description is embodied in a sampleConfiguration dictionary.  
  31.  * This contains the format type and subtype as well as any other information 
  32.  * needed to concretely specify the format.
  33.  *
  34.  * When processing components are connected to each other, a format negotiation
  35.  * takes place.  A processor configuration is set via the setConfiguration:
  36.  * message.  Configuration is continued until the components in question
  37.  * can handle the configuration request.
  38.  *
  39.  *
  40.  * Configuration process:
  41.  *
  42.  * After being created using alloc/init, the sample processor object is
  43.  * sent a setEnvironment: message.  The environment dictionary describes the
  44.  * current session and configuration goals.
  45.  *
  46.  * The dictionary passed into setConfiguration: typically has two keys:
  47.  * NTSampleInput, and NTSampleOutput.  The value of these keys are sub    
  48.  * dictionaries containing the desired input and output goals.  The component
  49.  * should examine these dictionaries and make any changes it wants in place.
  50.  * The configuration logic will note the changes and present them in turn to
  51.  * any other affected components.  The logic then continues bidding the 
  52.  * configuration until either convergence is reached, or a format cannot be
  53.  * agreed on.  If an agreement cannot be reached the configuration logic will
  54.  * try to use a format adaptor to make up the difference.
  55.  *
  56.  * Once a configuration is complete, each element of the configuration is
  57.  * sent a finalizeConfiguration message.  If this returns NO, the
  58.  * configuration is not considered viable, and is rejected.
  59.  *
  60.  * 
  61.  */
  62.  
  63. @protocol NTConfiguration <NSObject>
  64. - (void) setEnvironment:(bycopy NSDictionary *)environment;
  65. - (bycopy NSDictionary *) setConfiguration:
  66.         (bycopy NSDictionary *) config;
  67. - (bycopy NSDictionary *) configuration;
  68. - (BOOL) setOutputObject: obj;
  69. - (BOOL) finalizeConfiguration;
  70. - (bycopy NSDictionary *) measureConfiguration:
  71.         (bycopy NSDictionary *) query;
  72. @end
  73.  
  74. /*
  75.  * NTSampleProcessor protocol: specifies API by which samples are passed
  76.  * to a sample processor.
  77.  *
  78.  * The NTSampleProcessor may also be capable of providing a NTMutableSample
  79.  * buffer into which a previous NTSampleProcessor can deposit it's samples.
  80.  * This may be used to optimize output paths by letting the previous
  81.  * NTSampleProcessor deposit processed samples into dedicated hardware,
  82.  * such as a frame buffer or audio DMA buffer.
  83.  *
  84.  * If an NTSampleProcessor cannot vend a NTMutableSample buffer,
  85.  * it should still implement the inputBufferForPort: method,
  86.  * returning a value of nil.
  87.  *
  88.  * Graphics NTSampleProcessor which return an input buffer must guarantee that
  89.  * the buffer contains the accumulated contents of previous buffers passed to
  90.  * the object through writeSample:toPort:.  This is required to support
  91.  * compressors implementing temporal compression.
  92.  * 
  93.  * Objects which can return an output buffer must still support 
  94.  * writeSample:toPort: of NTSample objects which do not originate
  95.  * from the inputBufferForPort: method.
  96.  *
  97.  * An NTSampleProcessor which obtains a NTMutableSample object from another
  98.  * NTSampleProcessor is required to pass that NTMutableSample object back
  99.  * to the other NTSampleProcessor on it's next call to writeSample:toPort:.
  100.  *
  101.  * Output devices should implement the NTSampleProcessor protocol.
  102.  * The protocol does not fully define the API for an output device,
  103.  * however.  The output devices may also implement higher performance'
  104.  * API tuned for the specific data being handled.
  105.  */
  106.  
  107. /*
  108.  * NTSampleConsumer.  The actually writing methods are separated out here
  109.  * since some objects can implement these and be wired up into sample  
  110.  * processing pipelines (via setOutputObject:).  For example NTSampleFIFO
  111.  * and NTMedia implement this protocol.
  112.  */
  113.  
  114. @protocol NTSampleConsumer <NSObject>
  115. - (id <NTMutableSampleBuffer>)inputBuffer;
  116. - (void)writeSample: (id <NTSampleBuffer>) sample; 
  117. @end
  118.  
  119. @protocol NTSampleProcessor <NTConfiguration, NTSampleConsumer>
  120.  
  121. /*
  122.  * pause allows asynchronous devices to enqueue samples without
  123.  * actualization. (aka pre-roll)  When a processor is paused, it is
  124.  * in an enabled state, but is incapable of passing samples to it's outlet.
  125.  * -run places the sample processor in an enabled state, with the ability
  126.  * to pass samples to it's outlet.
  127.  *
  128.  * For example, in prerolling a movie, the output processor in a chain might
  129.  * be paused.  Samples would then be passed into the processing chain until
  130.  * [outputDevice samplesEnqueued] returns YES. 
  131.  */
  132. - (void)run;
  133. - (void)stop;
  134. - (BOOL)isStopped;     /* YES if passing samples to outlet is inhibited */
  135. - (BOOL)samplesEnqueued; /* YES if samples are enqueued */
  136.  
  137. /*
  138.  * flushSamples: waits for any enqueued samples to be completely processed,
  139.  * if abortFlag is true, enqueued samples need not be rendered and
  140.  * can be tossed. In any event, after this method is called, there
  141.  * is no pending data in the sample processor.
  142.  */
  143. - (void)flushSamples:(BOOL)abortFlag; 
  144. @end
  145.  
  146. /*
  147.  * An NTSamplePipeline implements the NTSampleProcessor protocol, 
  148.  * and contains a series of components used to implement the configured
  149.  * sample processing operation.  It's API also includes a method which returns
  150.  * the ordered list of processing component objects.  Each of these objects
  151.  * in turn implements the NTSampleProcessor protocol.  The list is ordered with
  152.  * the input processor first, and the sample sink, or output stage last.
  153.  *
  154.  * The list is owned by the NTSamplePipeline and should not be freed.
  155.  */
  156. @protocol NTSamplePipeline <NTSampleProcessor>
  157. - (NSArray *)nodeList;
  158. @end
  159.  
  160. /*
  161.  * NTSampleGenerator protocol: specifies API for an asynchronous sample source.
  162.  * The source will have it's sample target specified by means of the
  163.  * NTConfiguration protocol.
  164.  *
  165.  * Input devices should implement the NTSampleGenerator
  166.  * protocol.  The protocol does not fully define the API for a sample
  167.  * source, however.  The source devices may also implement higher
  168.  * performance API tuned for the specific data being handled.
  169.  *
  170.  * The -run and -pause methods do not imply anything with respect to sample
  171.  * ordering or timing.  They exist simply as a means of stopping or starting
  172.  * the flow of samples.  Temporal semantics and implications are outside the
  173.  * scope of this protocol.
  174.  */
  175. @protocol NTSampleGenerator <NTConfiguration>
  176. - (void)run;
  177. - (void)stop;
  178. - (BOOL)isStopped;
  179. @end
  180.  
  181. /*
  182.  * NTSampleFilter protocol:  This protocol is implemented by all objects
  183.  * which accept and transform samples into a new form.  Objects in this
  184.  * group include software compressors and decompressors.  The object performs
  185.  * it's encoding or decoding operation on 'sample', frees 'sample', and returns
  186.  * the new encoded or decoded sample.
  187.  *
  188.  * The implementor needs to be able to process samples `out-of-context'
  189.  * (i.e. without seeing neighboring samples in the sequence.).
  190.  * This is most often used in raw format converters but can also be used
  191.  * to compress or decompress `sync' samples in encoded form.
  192.  * The NEXTIME implementation guarantees that the sample filter will never be
  193.  * passed unordered non-sync samples. 
  194.  */
  195. @protocol NTSampleFilter <NTSampleProcessor>
  196. - (id <NTSampleBuffer>)processSampleFrom:(id <NTSampleBuffer>)sample;
  197. @end
  198.  
  199.  
  200.