LinkAttachments

Connects sample attachments for sequential playback.

Synopsis

Err LinkAttachments (Item Att1, Item Att2)

Description

This function specifies that the attachment Att2 will begin playing when attachment Att1 finishes. This is useful if you want to connect discontiguous sample buffers that are used for playing interleaved audio and video data. It is also a good way to construct big sound effects from a series of small sound effects.

If Att1's sample has a sustain loop, but no release loop, you can follow this with a call to ReleaseAttachment (Att1, NULL) to smoothly transition to Att2.

If Att1's sample has no loops, Att2 will automatically start as soon as Att1 completes (assuming that it has not completed prior to this function being called).

If, after linking Att1 to Att2, StopAttachment() is called on Att1 before it finishes, Att2 will not be automatically started. StopAttachment() on Att1 after it finishes has no effect.

All link remains in effect for multiple calls to StartInstrument() or StartAttachment(). That is, if you call LinkAttachments (Att1, Att2), Att1 will flow into Att2 upon completion of Att1 for every subsequent call to StartAttachment (Att1, NULL) (or StartInstrument() on the instrument belonging to Att1) if Att1 would normally be automatically started by starting the instrument).

An attachment (Att1) can link to no more than one attachment. An attachment (Att2) can be linked to multiple attachments. The most recent call to LinkAttachments() for Att1 takes precedence.

The pair of Attachments passed to this function must satisfy all of these requirements:

Both Attachments must be Sample Attachments.
Both Attachments must be attached to the same Instrument.
Both Attachments must be attached to the same FIFO of that Instrument.

Call LinkAttachments (Att1, 0) to remove a previous link from Att1.

A link does not interfere with a Cue associated with an attachment.

Deleting either Attachment, either Attachment's Sample, or the Instrument to which the Attachment belongs, breaks the link.

Arguments

Att1: The item number for the attachment that is to finish. Must be a sample attachment.

Att2: The item number for the attachment that is to begin playing. Must be a Sample Attachment attached to the same FIFO on the same Instrument as Att1. Can be 0 to remove a link from Att1.

Return Value

The function returns a non-negative value if successful or an error code (a negative value) if an error occurs.

Implementation

SWI implemented in Audio folio V20.

Caveats

In order for Att2 to start, Att1 must either be currently playing or yet to be played. If it has already completed by the time of this call, Att2 will not be started.

Associated Files

audio.h