Struct PHASESoundEvent

Source

pub struct PHASESoundEvent { /* private fields */ }

Available on crate feature PHASESoundEvent only.

Expand description

A PHASESoundEvent is an object that represents a playable sound event in the PHASE system.

Implementations§

Source §

pub unsafe fn initWithEngine_assetIdentifier_mixerParameters_error( this: Allocated<Self>, engine: &PHASEEngine, asset_identifier: &NSString, mixer_parameters: &PHASEMixerParameters, ) -> Result<Retained<Self>, Retained<NSError>>

Available on crate features PHASEEngine and PHASEMixer only.

Creates a new sound event instance

Parameter engine: The PHASEEngine object that the sound event will be played by.

Parameter assetIdentifier: The identifier registered with the Asset Registry for the particular PHASESoundEventNodeAsset that this sound instance will play. If the asset identifier is not registered, this function will fail.

Parameter mixerParameters: A dictionary of PHASEMixerParameters objects with keys that match the identifiers of the spatial mixers in the sound event

This will look up the asset in the asset registry and create the necessary objects to play the sound event

Source

pub unsafe fn initWithEngine_assetIdentifier_error( this: Allocated<Self>, engine: &PHASEEngine, asset_identifier: &NSString, ) -> Result<Retained<Self>, Retained<NSError>>

Available on crate feature PHASEEngine only.

Creates a new sound event instance

Parameter engine: The PHASEEngine object that the sound event will be played by.

Parameter assetIdentifier: The identifier registered with the Asset Registry for the particular PHASESoundEventNodeAsset that this sound event will play. If the asset identifier is not registered, this function will fail.

This will look up the asset in the asset registry and create the necessary objects to play the sound event

Source

pub unsafe fn prepareWithCompletion( &self, handler: Option<&DynBlock<dyn Fn(PHASESoundEventPrepareHandlerReason)>>, )

Available on crate features PHASETypes and block2 only.

Prepare the sound event

Parameter handler: The block that will be called when the PHASESoundEvent has finished preparing and is ready to start. Pass in nil for no handler.

This function notifies the engine to begin preparing a sound event, then returns immediately. Once the sound event is prepared (or has failed to prepare), you will receive a callback via the completion. If you call startWithCompletion() before receiving the callback, the sound event will start as soon as it’s prepared.

Source

pub unsafe fn startWithCompletion( &self, handler: Option<&DynBlock<dyn Fn(PHASESoundEventStartHandlerReason)>>, )

Available on crate features PHASETypes and block2 only.

Start the sound event

Parameter handler: The block that will be called when the sound event has stopped.

This function notifies the engine to start the sound event, then returns immediately. Once the sound event is playing (or has failed to start), you will receive a callback via the completion. Playback will begin immediately if the sound event has been prepared; otherwise, it will start as soon as it is finished preparing.

Source

pub unsafe fn startAtTime_completion( &self, when: Option<&AVAudioTime>, handler: Option<&DynBlock<dyn Fn(PHASESoundEventStartHandlerReason)>>, )

Available on crate features PHASETypes and block2 and objc2-avf-audio only.

Start the sound event

Parameter when: The desired start time based on the engine time retrieved from [PHASEEngine lastRenderTime] If the sound event starts immediately with an audible sound, it will begin rendering at this time. The sound event will otherwise begin operating at this time. A nil value will start the sound event immediately This time is not scaled by unitsPerSecond.

Parameter handler: The block that will be called when the sound event has stopped.

This function notifies the engine to start the sound event, then returns immediately. Once the sound event is playing (or has failed to start), you will receive a callback via the completion. Playback will begin at the requested time if the sound event has finished preparing in time. You may wait for preparation to finish with the [PHASESoundEvent prepare:completion] method before calling startAtTime, to ensure that the sound event will start at the desired time. However if the desired time is far enough into the future to allow for preparation to happen, you may skip calling prepare entirely and just call startAtTime.

Source

pub unsafe fn seekToTime_completion( &self, time: c_double, handler: Option<&DynBlock<dyn Fn(PHASESoundEventSeekHandlerReason)>>, )

Available on crate features PHASETypes and block2 only.

Seeks all leaf nodes in a PHASESoundEvent to a specified time relative to the start of the sound event.

This function notifies the engine to seek the sound event, then returns immediately. Once the sound event has seeked to the new offset (or has failed to seek), you will receive a callback via the completion. If any leaf nodes do not support seeking, those nodes will ignore this command. Nodes that have finished playing or have stopped will not seek. Nodes that are sleeping will seek, and will resume at the correct time when they wake up.

Note: The time is scaled by unitsPerSecond internally, so can be provided at the client’s native time scale.

Source

pub unsafe fn seekToTime_resumeAtEngineTime_completion( &self, time: c_double, engine_time: &AVAudioTime, handler: Option<&DynBlock<dyn Fn(PHASESoundEventSeekHandlerReason)>>, )

Available on crate features PHASETypes and block2 and objc2-avf-audio only.

Seeks all leaf nodes in a PHASESoundEvent to the specified time, and automatically resumes playback at the specified engine time.

Parameter time: The desired time position in seconds to seek the nodes to.

Parameter engineTime: The engine time to resume playback.

Parameter handler: The completion callback that will be called when seeking is complete.

This is a low latency convenience method that allows for tight deadlines to be met. However if the seek fails the node state will not be changed. You should check the callback and handle the failure appropriately. The time parameter will seek the nodes to the equivalent sample position based on the sample rate of the asset. The engineTime parameter is the engine timestamp to resume rendering at, based off of [PHASEEngine lastRenderTime]. If any leaf nodes do not support seeking, those nodes will ignore this command. Nodes that have finished playing or have stopped will not seek. The time parameter is in seconds and will be scaled by unitsPerSecond. The time in the AVAudioTime structure is not scaled by unitsPerSecond. The engineTime parameter will use the sample time if valid, if not, then the host time if valid.

Source

pub unsafe fn pause(&self)

Pause the sound event.

Source

pub unsafe fn resume(&self)

Resume the sound event.

Source

pub unsafe fn resumeAtTime(&self, time: Option<&AVAudioTime>)

Available on crate feature objc2-avf-audio only.

Resume the sound event at a specific time

Parameter time: The desired start time based on the engine time retrieved from [PHASEEngine lastRenderTime]

A nil time parameter will resume immediately. The device time is not scaled by UnitsPerSecond and is in seconds.

Source

pub unsafe fn stopAndInvalidate(&self)

stop and invalidate the sound event

Source

pub unsafe fn renderingState(&self) -> PHASERenderingState

Available on crate feature PHASETypes only.

Sound Event’s current rendering state

Source

pub unsafe fn prepareState(&self) -> PHASESoundEventPrepareState

Available on crate feature PHASETypes only.

Sound Event’s current preparation state

Source

pub unsafe fn metaParameters( &self, ) -> Retained<NSDictionary<NSString, PHASEMetaParameter>>

Available on crate feature PHASEMetaParameter only.

A Dictionary containing the MetaParameters associated with this sound event

Source

pub unsafe fn mixers(&self) -> Retained<NSDictionary<NSString, PHASEMixer>>

Available on crate feature PHASEMixer only.

A Dictionary containing the mix nodes associated with this sound event

Source

pub unsafe fn pushStreamNodes( &self, ) -> Retained<NSDictionary<NSString, PHASEPushStreamNode>>

Available on crate feature PHASESoundEventNodes only.

A Dictionary containing the push stream nodes associated with this sound event, for pushing buffers to.

Source

pub unsafe fn pullStreamNodes( &self, ) -> Retained<NSDictionary<NSString, PHASEPullStreamNode>>

Available on crate feature PHASESoundEventNodes only.

A Dictionary containing the pull stream nodes associated with this sound event, for setting renderBlocks on.

Source

pub unsafe fn isIndefinite(&self) -> bool

A boolean that tell if this sound event will run indefinitely, or finish executing on its own

Methods from Deref<Target = NSObject>§

Source

pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !

Handle messages the object doesn’t recognize.

See Apple’s documentation for details.

Methods from Deref<Target = AnyObject>§

Source

pub fn class(&self) -> &'static AnyClass

Dynamically find the class of this object.

§Panics

May panic if the object is invalid (which may be the case for objects returned from unavailable init/new methods).

§Example

Check that an instance of NSObject has the precise class NSObject.

use objc2::ClassType;
use objc2::runtime::NSObject;

let obj = NSObject::new();
assert_eq!(obj.class(), NSObject::class());

Source

pub unsafe fn get_ivar<T>(&self, name: &str) -> &T
where T: Encode,

👎Deprecated: this is difficult to use correctly, use Ivar::load instead.

Use Ivar::load instead.

§Safety

The object must have an instance variable with the given name, and it must be of type T.

See Ivar::load_ptr for details surrounding this.

Source

pub fn downcast_ref<T>(&self) -> Option<&T>
where T: DowncastTarget,

Attempt to downcast the object to a class of type T.

This is the reference-variant. Use Retained::downcast if you want to convert a retained object to another type.

§Mutable classes

Some classes have immutable and mutable variants, such as NSString and NSMutableString.

When some Objective-C API signature says it gives you an immutable class, it generally expects you to not mutate that, even though it may technically be mutable “under the hood”.

So using this method to convert a NSString to a NSMutableString, while not unsound, is generally frowned upon unless you created the string yourself, or the API explicitly documents the string to be mutable.

See Apple’s documentation on mutability and on isKindOfClass: for more details.

§Generic classes

Objective-C generics are called “lightweight generics”, and that’s because they aren’t exposed in the runtime. This makes it impossible to safely downcast to generic collections, so this is disallowed by this method.

You can, however, safely downcast to generic collections where all the type-parameters are AnyObject.

§Panics

This works internally by calling isKindOfClass:. That means that the object must have the instance method of that name, and an exception will be thrown (if CoreFoundation is linked) or the process will abort if that is not the case. In the vast majority of cases, you don’t need to worry about this, since both root objects NSObject and NSProxy implement this method.

§Examples

Cast an NSString back and forth from NSObject.

use objc2::rc::Retained;
use objc2_foundation::{NSObject, NSString};

let obj: Retained<NSObject> = NSString::new().into_super();
let string = obj.downcast_ref::<NSString>().unwrap();
// Or with `downcast`, if we do not need the object afterwards
let string = obj.downcast::<NSString>().unwrap();

Try (and fail) to cast an NSObject to an NSString.

use objc2_foundation::{NSObject, NSString};

let obj = NSObject::new();
assert!(obj.downcast_ref::<NSString>().is_none());

Try to cast to an array of strings.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);
// This is invalid and doesn't type check.
let arr = arr.downcast_ref::<NSArray<NSString>>();

This fails to compile, since it would require enumerating over the array to ensure that each element is of the desired type, which is a performance pitfall.

Downcast when processing each element instead.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);

for elem in arr {
    if let Some(data) = elem.downcast_ref::<NSString>() {
        // handle `data`
    }
}