From 1f7f4083dd98c7e670489b8218a8369c141d638e Mon Sep 17 00:00:00 2001 From: Juju Adams Date: Sat, 1 Jun 2024 13:41:59 +0100 Subject: [PATCH] Update Functions-Queue.md --- docs/6.0/Functions-Queue.md | 136 ++++++++++++++++++++++++------------ 1 file changed, 90 insertions(+), 46 deletions(-) diff --git a/docs/6.0/Functions-Queue.md b/docs/6.0/Functions-Queue.md index a1dc4e04..bbcb92af 100644 --- a/docs/6.0/Functions-Queue.md +++ b/docs/6.0/Functions-Queue.md @@ -10,13 +10,29 @@ #### **Description** -*Returns:* N/A (`undefined`) +*Returns:* Queue voice + +|Name |Datatype |Purpose | +|-----------|------------------|-------------------------------------------------------------------------------| +|`behaviour`|`VINYL_QUEUE` enum|Behaviour to use for the queue, see below | +|`loopQueue`|boolean |Whether to loop the queue by pushing stopping sounds to the bottom of the queue| +|`[gain]` |number |Local gain to set for the queue | + +Create a new sound queue. A sound queue is used to play audio in a particular sequence which is useful to set up dynamix soundtracks, in-game radio stations etc. This function returns a queue index which can be used like the voice index returned by `VinylPlay()`. This means you can call `VinylFadeOut()`, `VinylPause()`, `VinylSetGain()` etc. targeting a queue and the queue will behave appropriately. + +There are three behaviours that a sound queue can use, found in `VINYL_QUEUE` enum: + +|Enum Member |Behaviour | +|---------------|-----------------------------------------------------------------------| +|`.DONT_LOOP` |Play each sound in the queue once | +|`.LOOP_ON_LAST`|Play each sound in the queue once until the last sound, which is looped| +|`.LOOP_EACH` |Loop each sound | -|Name |Datatype |Purpose | -|-----------|------------------|-------------------------| -|`behaviour`|`VINYL_QUEUE` enum| | -|`loopQueue`|boolean | | -|`[gain]` |number | | +The currently playing sound can be manually set to loop or not loop by calling `VinylSetLoop()` targeting the queue. If a sound is not looping and completes playing then the next sound in the queue will be played. + +?> If you push a new sound to a `.LOOP_ON_LAST` queue Vinyl will **not** automatically set a currently looping sound to stop looping. You will need to call `VinylSetLoop(..., false)` to stop a loop in all cases. + +The queue itself can be set to loop as well. Internally this is achieved by pushing stopping sounds to the bottom of the queue. A queue that is itself set to loop will never trigger `.LOOP_ON_LAST`. #### **Example** @@ -38,11 +54,13 @@ No example provided. *Returns:* N/A (`undefined`) -|Name |Datatype |Purpose | -|-----------------|------------------|-------------------------| -|`voice` |voice | | -|`behaviour` |`VINYL_QUEUE` enum| | -|`[setForPlaying]`|boolean | | +|Name |Datatype |Purpose | +|-----------------|------------------|--------------------------------------------------------------------------------------------------------------------| +|`voice` |voice |Queue voice to target | +|`behaviour` |`VINYL_QUEUE` enum|Behaviour to use for the queue, see `VinylQueueCreate()` | +|`[setForPlaying]`|boolean |Optional, defaults to `true`. Whether to immediately apply the new looping behaviour for the currently playing sound| + +Sets the target queue's behaviour. Please see `VinylQueueCreate()` for more information. #### **Example** @@ -62,11 +80,13 @@ No example provided. #### **Description** -*Returns:* N/A (`undefined`) +*Returns:* Number or `undefined` |Name |Datatype|Purpose | |-------|--------|-------------------------| -|`voice`|voice | | +|`voice`|voice |Queue voice to target | + +Returns the target queue's behaviour. #### **Example** @@ -88,10 +108,14 @@ No example provided. *Returns:* N/A (`undefined`) -|Name |Datatype|Purpose | -|-------|--------|-------------------------| -|`voice`|voice | | -|`state`|boolean | | +|Name |Datatype|Purpose | +|-----------|--------|-------------------------| +|`voice` |voice |Queue voice to target | +|`loopQueue`|boolean |Whether to loop the queue by pushing stopping sounds to the bottom of the queue| + +Sets whether the queue itself should loop. + +?> If you'd like to alter the loop state of the currently playing sound then use `VinylGetLoop()`. #### **Example** @@ -111,11 +135,15 @@ No example provided. #### **Description** -*Returns:* N/A (`undefined`) +*Returns:* Boolean |Name |Datatype|Purpose | |-------|--------|-------------------------| -|`voice`|voice | | +|`voice`|voice |Queue voice to target | + +Returns whether the queue itself is set to loop. + +?> If you'd like to return the loop state of the currently playing sound then use `VinylGetLoop()`. #### **Example** @@ -137,10 +165,12 @@ No example provided. *Returns:* N/A (`undefined`) -|Name |Datatype |Purpose | -|------------|---------------|-------------------------| -|`voice` |voice | | -|`soundArray`|array of sounds| | +|Name |Datatype |Purpose | +|------------|---------------|------------------------------------| +|`voice` |voice |Queue voice to target | +|`soundArray`|array of sounds|Array of sounds to set for the queue| + +Sets the queue of sounds for a queue created by VinylQueueCreate(). This function will "save" a copy of the input array which means that any adjustment to the input array after calling `VinylQueueSetArray()` will not alter what sounds are played back. You will need to call `VinylQueueSetArray()` again if you want to change the internal sound array. #### **Example** @@ -160,11 +190,13 @@ No example provided. #### **Description** -*Returns:* N/A (`undefined`) +*Returns:* Array of sounds -|Name |Datatype|Purpose | -|-------|--------|-------------------------| -|`voice`|voice | | +|Name |Datatype |Purpose | +|------------|---------------|------------------------------------| +|`voice` |voice |Queue voice to target | + +Returns the array of sounds that are queued for the target queue. This queue does not include the currently playing sound. This function returns a copy of the internal array that the queue uses. Modifying the returned array will therefore not alter the queue's behaviour and you will need to use `VinylQueueSetArray()` to "save" any changes you've made to the array. #### **Example** @@ -186,10 +218,12 @@ No example provided. *Returns:* N/A (`undefined`) -|Name |Datatype|Purpose | -|-------|--------|-------------------------| -|`voice`|voice | | -|`sound`|sound | | +|Name |Datatype|Purpose | +|-------|--------|----------------------------------------| +|`voice`|voice |Queue voice to target | +|`sound`|sound |Sound to push to the bottom of the queue| + +Pushes a sound to the bottom of a queue's array of sounds. If the queue is empty then the next sound will be played at the start of the next frame. #### **Example** @@ -211,10 +245,12 @@ No example provided. *Returns:* N/A (`undefined`) -|Name |Datatype|Purpose | -|-------|--------|-------------------------| -|`voice`|voice | | -|`sound`|sound | | +|Name |Datatype|Purpose | +|-------|--------|-------------------------------------| +|`voice`|voice |Queue voice to target | +|`sound`|sound |Sound to push to the top of the queue| + +Pushes a sound to the top of a queue's array of sounds. Once the currently playing sound has stopped, the sound pushed by this function will play. If the queue is empty then the next sound will be played at the start of the next frame. #### **Example** @@ -234,12 +270,14 @@ No example provided. #### **Description** -*Returns:* N/A (`undefined`) +*Returns:* Boolean -|Name |Datatype|Purpose | -|-------|--------|-------------------------| -|`voice`|voice | | -|`sound`|sound | | +|Name |Datatype|Purpose | +|-------|--------|---------------------| +|`voice`|voice |Queue voice to target| +|`sound`|sound |Sound to check for | + +Returns whether a queue's array of sounds contains the specified target sound. This function will return `true` if the currently playing sound also matches the target sound. #### **Example** @@ -261,9 +299,13 @@ No example provided. *Returns:* N/A (`undefined`) -|Name |Datatype|Purpose | -|-------|--------|-------------------------| -|`voice`|voice | | +|Name |Datatype|Purpose | +|-------|--------|---------------------| +|`voice`|voice |Queue voice to target| + +Clears all sounds in a queue's array of sounds. + +!> This function won't stop the currently playing sound. Use `VinylStop()` to stop the currently playing sound in a queue. #### **Example** @@ -285,9 +327,11 @@ No example provided. *Returns:* N/A (`undefined`) -|Name |Datatype|Purpose | -|-------|--------|-------------------------| -|`voice`|voice | | +|Name |Datatype|Purpose | +|-------|--------|---------------------| +|`voice`|voice |Queue voice to target| + +Destroys a Vinyl queue. This stops any currently playing audio and renders the queue inoperable. This function is provided for convenience and you don't have to call this function to manage memory. #### **Example**