# CreateEnvelope

Creates an envelope for a sample or cue.

### Synopsis

`Item CreateEnvelope (DataTimePair *Points, int32 Numpoints,int32 SustainBegin, int32 SustainEnd)`

### Description

Creates an envelope for a sample or a cue. Envelopes are described by an array of pairs of time and data. It can be used to specify a loop for sustained sound.

Data typically ranges from -32,768 to 32,767 or 0 to 65,535, and must be sign-extended to 32 bits. Loops are specified as point indices. For more information, read the description of envelopes in the Music Programmer's Guide.

When you are finished with the envelope, you should call `DeleteEnvelope()` to delete it and deallocate its resources.

### Arguments

Points
  An array of DataTimePair values giving delta time in milliseconds accompanied by data values. This becomes the value of the envelope item's AF_TAG_ADDRESS tag argument described in SetAudioItemInfo(). The Points array is not copied: it must remain valid for the life of the Envelope Item or until it is replaced with another array of Points by a call to `SetAudioItemInfo()`.

NumPoints
  The number of points in the array. This becomes the value of the envelope item's AF_TAG_FRAMES tag argument.

SustainBegin
  The beginning index of the loop. This becomes the value of the envelope item's AF_TAG_SUSTAINBEGIN tag argument. Set to - 1 for no sustain loop.

SustainEnd
  The ending index of the loop. This becomes the value of the envelope item's AF_TAG_SUSTAINEND tag argument. Set to -1 for no sustain loop. Otherwise must be >= SustainBegin.

### Return Value

The function returns the item number of the envelope (a positive value) or an error code (a negative value) if an error occurs.

### Implementation

Folio call implemented in Audio folio V20.

### Associated Files

audio.h

### See Also

``DeleteEnvelope`(), AttachEnvelope()`