/libs/ObjectAL/OpenAL/ALCaptureDevice.h

  1//
  2//  ALCaptureDevice.h
  3//  ObjectAL
  4//
  5//  Created by Karl Stenerud on 10-01-11.
  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 <OpenAL/alc.h>
 29
 30
 31#pragma mark ALCaptureDevice
 32
 33/**
 34 * *UNIMPLEMENTED FOR IOS* An OpenAL device for capturing sound data.
 35 * Note: This functionality is NOT implemented in iOS OpenAL! <br>
 36 * This class is a placeholder in case such functionality is added in a future iOS SDK.
 37 */
 38@interface ALCaptureDevice : NSObject
 39{
 40	ALCdevice* device;
 41}
 42
 43
 44#pragma mark Properties
 45
 46/** The number of capture samples available. */
 47@property(readonly) int captureSamples;
 48
 49/** The OpenAL device pointer. */
 50@property(readonly) ALCdevice* device;
 51
 52/** List of strings describing all extensions available on this device (NSString*). */
 53@property(readonly) NSArray* extensions;
 54
 55/** The specification revision for this implementation (major version). */
 56@property(readonly) int majorVersion;
 57
 58/** The specification revision for this implementation (minor version). */
 59@property(readonly) int minorVersion;
 60
 61
 62#pragma mark Object Management
 63
 64/** Open the specified device.
 65 *
 66 * @param deviceSpecifier The name of the device to open (nil = default device).
 67 * @param frequency The frequency to capture at.
 68 * @param format The audio format to capture as.
 69 * @param bufferSize The size of buffer that the device must allocate for audio capture.
 70 * @return A new capture device.
 71 */
 72+ (id) deviceWithDeviceSpecifier:(NSString*) deviceSpecifier
 73					   frequency:(ALCuint) frequency
 74						  format:(ALCenum) format
 75					  bufferSize:(ALCsizei) bufferSize;
 76
 77/** Open the specified device.
 78 *
 79 * @param deviceSpecifier The name of the device to open (nil = default device).
 80 * @param frequency The frequency to capture at.
 81 * @param format The audio format to capture as.
 82 * @param bufferSize The size of buffer that the device must allocate for audio capture.
 83 * @return The initialized capture device.
 84 */
 85- (id) initWithDeviceSpecifier:(NSString*) deviceSpecifier
 86					 frequency:(ALCuint) frequency
 87						format:(ALCenum) format
 88					bufferSize:(ALCsizei) bufferSize;
 89
 90/** Close any OS resources in use by this object.
 91 * Any operations called on this object after closing will likely fail.
 92 */
 93- (void) close;
 94
 95
 96#pragma mark Audio Capture
 97
 98/** Start capturing samples.
 99 *
100 * @return TRUE if the operation was successful.
101 */
102- (bool) startCapture;
103
104/** Stop capturing samples.
105 *
106 * @return TRUE if the operation was successful.
107 */
108- (bool) stopCapture;
109
110/** Move captured samples to the specified buffer.
111 * This method will fail if less than the specified number of samples have been captured.
112 *
113 * @param numSamples The number of samples to move.
114 * @param buffer the buffer to move the samples into.
115 * @return TRUE if the operation was successful.
116 */
117- (bool) moveSamples:(ALCsizei) numSamples toBuffer:(ALCvoid*) buffer;
118
119
120#pragma mark Extensions
121
122/** Check if the specified extension is present.
123 *
124 * @param name The name of the extension to check.
125 * @return TRUE if the extension is present.
126 */
127- (bool) isExtensionPresent:(NSString*) name;
128
129/** Get the address of the specified procedure (C function address).
130 *
131 * @param functionName The name of the procedure to get.
132 * @return the procedure's address, or NULL if it wasn't found.
133 */
134- (void*) getProcAddress:(NSString*) functionName;
135
136
137@end