/libs/ObjectAL/OpenAL/ALListener.h

  1//
  2//  ALListener.h
  3//  ObjectAL
  4//
  5//  Created by Karl Stenerud on 10-01-07.
  6//
  7// Copyright 2009 Karl Stenerud
  8//
  9// Licensed under the Apache License, Version 2.0 (the "License");
 10// you may not use this file except in compliance with the License.
 11// You may obtain a copy of the License at
 12//
 13// http://www.apache.org/licenses/LICENSE-2.0
 14//
 15// Unless required by applicable law or agreed to in writing, software
 16// distributed under the License is distributed on an "AS IS" BASIS,
 17// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 18// See the License for the specific language governing permissions and
 19// limitations under the License.
 20//
 21// Note: You are NOT required to make the license available from within your
 22// iOS application. Including it in your project is sufficient.
 23//
 24// Attribution is not required, but appreciated :)
 25//
 26
 27#import <Foundation/Foundation.h>
 28#import "ALTypes.h"
 29#import "OALSuspendHandler.h"
 30
 31@class ALContext;
 32
 33
 34#pragma mark ALListener
 35
 36/**
 37 * The listener represents the user who is listening to sounds in 3D space.
 38 * This object controls his position, orientation, and velocity, as well as providing a master
 39 * gain. <br>
 40 * A context contains one and only one listener.
 41 */
 42@interface ALListener : NSObject <OALSuspendManager>
 43{
 44	ALContext* context; // Weak reference
 45	bool muted;
 46	float gain;
 47	
 48	/** Handles suspending and interrupting for this object. */
 49	OALSuspendHandler* suspendHandler;
 50}
 51
 52
 53#pragma mark Properties
 54
 55/** The context this listener belongs to. */
 56@property(readonly) ALContext* context;
 57
 58/** Causes this listener to stop hearing sound.
 59 * It's called "muted" rather than "deaf" to give a consistent name with other mute functions.
 60 */
 61@property(readwrite,assign) bool muted;
 62
 63/** Gain (volume), affecting every sound this listener hears (0.0 = no sound, 1.0 = max volume).
 64 * Only valid if this listener's context is the current context.
 65 */
 66@property(readwrite,assign) float gain;
 67
 68/** Orientation (up: x, y, z, at: x, y, z).
 69 * Only valid if this listener's context is the current context.
 70 */
 71@property(readwrite,assign) ALOrientation orientation;
 72
 73/** Position (x, y, z).
 74 * Only valid if this listener's context is the current context.
 75 */
 76@property(readwrite,assign) ALPoint position;
 77
 78/** Velocity (x, y, z).
 79* Only valid if this listener's context is the current context.
 80*/
 81@property(readwrite,assign) ALVector velocity;
 82
 83
 84#pragma mark Object Management
 85
 86/** (INTERNAL USE) Create a listener for the specified context.
 87 *
 88 * @param context the context to create this listener on.
 89 * @return A new listener.
 90 */
 91+ (id) listenerForContext:(ALContext*) context;
 92
 93/** (INTERNAL USE) Initialize a listener for the specified context.
 94 *
 95 * @param context the context to create this listener on.
 96 * @return The initialized listener.
 97 */
 98- (id) initWithContext:(ALContext*) context;
 99
100@end