MKSynthData.h

/*
  $Id: MKSynthData.h 3251 2005-05-11 07:59:04Z leighsmith $
  Defined In: The MusicKit

  Description:
    MKSynthData objects represent DSP memory that's used in music synthesis.
    For example, you can use a MKSynthData object to load predefined data
    for wavetable synthesis or to store DSP-computed data to create a
    digital delay.  Perhaps the most common use of MKSynthData is to create
    a location through which MKUnitGenerators can pass data.  This type of
    MKSynthData object is called a patchpoint.  For example, in frequency
    modulation an oscillator MKUnitGenerator writes its output to a
    patchpoint which can then be read by another oscillator as its
    frequency input.
   
    You never create MKSynthData objects directly in an application, they
    can only be created by the MKOrchestra through its
    allocSynthData:length: or allocPatchpoint: methods.  MKSynthData objects
    are typically owned by a MKSynthPatch, an object that configures a set
    of MKSynthData and MKUnitGenerator objects into a DSP software instrument.
   
    The methods setData: and setToConstant: are used to load a MKSynthData
    object with data from an array or as a constant, respectively.  These
    methods are simple versions of the more thorough methods
    setData:length:offset: and setToConstant:length:offset:, which allow you
    to load an arbitrary amount of data into any portion of the
    MKSynthData's memory.  The data in a MKSynthData object, like all DSP data
    used in music synthesis, is 24-bit fixed point words (data type
    DSPDatum).  You can declare a MKSynthData to be read-only by sending it
    the message setReadOnly:YES.  You can't change the data in a read-only
    MKSynthData object.
   
    An instance of MKSynthData consists of an MKOrchAddrStruct, a structure
    that describes the DSP location of the object's data, and a length
    instance variable, an integer value that measures the size of the data
    in DSPDatum words.  However, it doesn't contain a copy of the memory
    itself.  When you load data into a MKSynthData, it's instantly sent to
    the DSP device driver.
   
    DSP memory allocation and management is explained in the MKOrchestra
    class description; many of the return types used here, such as
    DSPAddress and DSPMemorySpace, are described in MKOrchestra.  In
    general, the design of the MKOrchestra makes intimate knowledge of the
    details of the DSP unnecessary.
   
    CF: MKSynthPatch, MKOrchestra, MKUnitGenerator

  Original Author: David A. Jaffe

  Copyright (c) 1988-1992, NeXT Computer, Inc.
  Portions Copyright (c) 1994 NeXT Computer, Inc. and reproduced under license from NeXT
  Portions Copyright (c) 1994 Stanford University  
  Portions Copyright (c) 1999-2001, The MusicKit Project.
*/
#ifndef __MK_SynthData_H___
#define __MK_SynthData_H___

#import <Foundation/NSObject.h>

@interface MKSynthData : NSObject
{
    /* DO NOT CHANGE THE POSITION OF THE FOLLOWING BLOCK OF IVARS! */
    id synthPatch;      /* The MKSynthPatch that owns this object (if any). */
    id orchestra;       /* The orchestra on which the SynthElement object is allocated. */

@private
    unsigned short _orchIndex;
    unsigned short _synthPatchLoc;
    id _sharedKey;
    BOOL _protected;
    int _instanceNumber;
    /* END OF INVARIANT IVARS */

    unsigned int length;       /* Length of allocated memory in words. */
    MKOrchAddrStruct orchAddr; /* Structure that directly represents DSP memory. Contains size, space, etc.*/
    BOOL readOnly;             /* YES if the object's data is read-only. */

    MKOrchMemStruct _reso;     /* Each instance has its own here */
    BOOL isModulus;
}

+new;
+ allocWithZone:(NSZone *)zone;
+alloc;
-copy;

- copyWithZone:(NSZone *)zone;
 /* These methods are overridden to return [self doesNotRecognize]. 
    You never create, free or copy MKUnitGenerators directly. These operations
    are always done via an MKOrchestra object. */

- (void) dealloc; /* was "free" before conversion */
 /* Same as [self dealloc]. */


- clear; 

- (unsigned int) length; 

- (DSPAddress) address; 

- (DSPMemorySpace) memorySpace; 

- (MKOrchAddrStruct *) orchAddrPtr; 

- (BOOL) isModulus;

- setData: (DSPDatum *) dataArray length: (unsigned int) len offset: (int) off; 

- setShortData: (short *) dataArray length: (unsigned int) len offset: (int) off;

- setData: (DSPDatum *) dataArray; 

- setShortData: (short *) dataArray;

- setToConstant: (DSPDatum) value length: (unsigned int) len offset: (int) off; 

- setToConstant: (DSPDatum) value;    

- run;

- idle;

- (double) finish;

+ orchestraClass;

- orchestra; 

/* 
  Deallocates the receiver and frees its MKSynthPatch, if any. Returns nil.
  sb: was dealloc, but this may differ from OpenStep's
  ideas of dealloc. I have changed things here and
  in MKSynthPatch h/m, MKUnitGenerator.h (not m), and in
  synthElementMethods.m
 */
- (void) mkdealloc;     


- (BOOL) isAllocated;

- (BOOL) isFreeable; 

- synthPatch; 

- setReadOnly: (BOOL) readOnlyFlag;

- (BOOL) readOnly;

- (int) referenceCount;

 /* -read: and -write: 
  * Note that archiving is not supported in the MKSynthData object, since,
  * by definition the MKSynthData instance only exists when it is resident on
  * a DSP.
  */


- readDataUntimed: (DSPDatum *) dataArray length: (unsigned int) len offset: (int) off;

- readShortDataUntimed: (short *) dataArray length: (unsigned int) len offset: (int) off;

@end



#endif

---