Class TSound

DescriptionHierarchyFieldsMethodsProperties

Unit

Declaration

type TSound = class(TObject)

Description

Sound (an allocated OpenAL sound source).

Hierarchy

  • TObject
  • TSound

Overview

Methods

Public constructor Create;
Public destructor Destroy; override;
Public procedure Release; virtual;
Public function PlayingOrPaused: boolean;

Properties

Public property ALSource: TALuint read FALSource;
Public property Used: boolean read FUsed default false;
Public property Importance: Integer read FImportance default 0;
Public property UserData: TObject read FUserData write FUserData;
Public property OnRelease: TSoundEvent read FOnRelease write FOnRelease;
Public property Position: TVector3Single read FPosition write SetPosition;
Public property Velocity: TVector3Single read FVelocity write SetVelocity;
Public property Looping: boolean read FLooping write SetLooping;
Public property Relative: boolean read FRelative write SetRelative;
Public property Gain: Single read FGain write SetGain;
Public property MinGain: Single read FMinGain write SetMinGain;
Public property MaxGain: Single read FMaxGain write SetMaxGain;
Public property Buffer: TSoundBuffer read FBuffer write SetBuffer;
Public property Pitch: Single read FPitch write SetPitch;
Public property RolloffFactor: Single read FRolloffFactor write SetRolloffFactor;
Public property ReferenceDistance: Single read FReferenceDistance write SetReferenceDistance;
Public property MaxDistance: Single read FMaxDistance write SetMaxDistance;

Description

Methods

Public constructor Create;

Create sound. This allocates actual OpenAL source.

Exceptions raised
ENoMoreOpenALSources
If no more sources available. It should be caught and silenced by TSoundAllocator.AllocateSound.
Public destructor Destroy; override;
 
Public procedure Release; virtual;

Stops playing the source, sets Used to False, and calls OnRelease (if assigned).

You can call this yourself if you want to stop playing the sound. It's preferable to call this (instead of manually calling alSourceStop), because this will immediately mark Used property as False and will call OnRelease. Otherwise we would have to get source state at some time (they are checked in AllocateSound) and check it, then see that it's no longer playing.

You can call this only when Used = True.

Public function PlayingOrPaused: boolean;

Is the sound playing or paused. This is almost always True for sounds returned by TSoundAllocator.AllocateSound, when it stops being True — the sound engine will realize it (soon), which will cause Release and OnRelease being automatically called, and this TSound may then be reused for playing other sounds.

Properties

Public property ALSource: TALuint read FALSource;
 
Public property Used: boolean read FUsed default false;

Do we play something. Sources that are not Used are simply OpenAL allocated sources that are not used right now, and will be used when we will need them.

Public property Importance: Integer read FImportance default 0;

The priority of keeping this source, relevant only when Used.

Higher Importance means that it's more important to keep it. (I didn't name this property "Priority" so that it's obvious that higher Importance means more important sound).

Public property UserData: TObject read FUserData write FUserData;

Any data comfortable to keep here by the caller of TSoundAllocator.AllocateSound. It should be initialized after calling TSoundAllocator.AllocateSound, and should be finalized in OnRelease.

Public property OnRelease: TSoundEvent read FOnRelease write FOnRelease;

Called when this OpenAL allocated sound will no longer be used. It may stop be used because there are more demanding sources (see Importance and to keep MaxAllocatedSources) and we must assign this OpenAL sound slot to something else, or it may stop be used because it simply stopped playing.

But note that we do not make any guarantees that sources that stopped playing will be immediately reported to OnRelease. In fact, a source may be considered in Used = True state for a long time until it stopped playing. That's not a problem for this unit — TSoundAllocator.AllocateSound is smart, and it may actually check (and eventually mark with Release) whether some sources are in playing state, to avoid allocating unnecessary sources. However, if this is a problem for you (because e.g. you do some expensive operations to update all used sources every time) and you really desire OnRelease to be called quickly after sound stoppped playing, you may call TSoundAllocator.Refresh from time to time.

In this event you should make sure to delete all references to this sound, because the TSound instance may be freed (or reused for other means) after calling OnRelease. For the same reason, after calling this, we always clear it (set OnRelease to Nil).

It's guaranteed that when this will be called, Used will be False and PlayingOrPaused will be False.

Public property Position: TVector3Single read FPosition write SetPosition;
 
Public property Velocity: TVector3Single read FVelocity write SetVelocity;
 
Public property Looping: boolean read FLooping write SetLooping;
 
Public property Relative: boolean read FRelative write SetRelative;
 
Public property Gain: Single read FGain write SetGain;
 
Public property MinGain: Single read FMinGain write SetMinGain;
 
Public property MaxGain: Single read FMaxGain write SetMaxGain;
 
Public property Buffer: TSoundBuffer read FBuffer write SetBuffer;
 
Public property Pitch: Single read FPitch write SetPitch;
 
Public property RolloffFactor: Single read FRolloffFactor write SetRolloffFactor;
 
Public property ReferenceDistance: Single read FReferenceDistance write SetReferenceDistance;
 
Public property MaxDistance: Single read FMaxDistance write SetMaxDistance;
 

Generated by PasDoc 0.13.0 on 2014-08-30 12:10:41