-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.in
78 lines (60 loc) · 2.46 KB
/
README.in
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
## jarabica
The `jarabica` package attempts to provide a type-safe, mildly object-oriented
frontend to the [OpenAL](https://www.openal.org/) API. Currently, it uses the
high-quality [LWJGL](https://www.lwjgl.org/) bindings internally, and wraps
them with a thin layer of short-lived immutable types for safety and efficiency.
It strongly separates the API and implementation to allow for easy unit testing
and mocking of code that calls OpenAL.
## Features
* Type-safe [OpenAL](https://www.openal.org/) frontend.
* Strong separation of API and implementation to allow for switching to
different bindings at compile-time.
* Strongly-typed interfaces with a heavy emphasis on immutable value types.
* Fully documented (JavaDoc).
* Example code included.
* High coverage test suite.
* [OSGi-ready](https://www.osgi.org/)
* [JPMS-ready](https://en.wikipedia.org/wiki/Java_Platform_Module_System)
* ISC license.
## Usage
The `jarabica` package works in the same manner as the OpenAL API, but with
adjustments to make the API feel more like a Java API. Create a _device factory_
from which to create devices. The device factory implementation chosen
essentially decides which underlying OpenAL bindings will be used; currently,
the only real implementation is based on LWJGL.
```
val devices = new JALWDeviceFactory();
```
Enumerate the available audio devices:
```
List<JADeviceDescription> deviceDescriptions = devices.enumerateDevices();
```
Inspect the list of returned devices, and select the one that is most
appropriate to your application. Use the description of the device to
open the device:
```
try (JADeviceType device = devices.openDevice(deviceDescriptions.get(0))) {
...
}
```
With the open device, it's necessary to create a _context_.
```
JAContextType context = device.createContext();
```
The context value follows the usual OpenAL thread-safety rules; a context
must be _made current_ on the current thread before any operations can be
performed using it. Creating a context automatically makes it current on
the calling thread.
The context value can then be used to create OpenAL _sources_ and _buffers_
in a manner familiar to anyone experienced with OpenAL.
```
try (var source = context.createSource()) {
try (var buffer = context.createBuffer()) {
...
}
}
```
## Example Application
A [demo application](com.io7m.jarabica.demo) is included that demonstrates
how to use the API correctly, and also demonstrates numerous extensions such
as the ubiquitous EFX extension.