0
# ISO Resource Management
1

2
IEEE 1394 (FireWire) bus resource allocation and management for bandwidth and channel allocation in libdc1394.
3

4
## Capabilities
5

6
### Channel Allocation
7

8
Manages IEEE 1394 isochronous channel allocation for camera communication.
9

10
```java { .api }
11
/**
12
 * Allocates an IEEE 1394 isochronous channel for camera communication
13
 * @param camera Camera instance
14
 * @param channels_allowed Bitmask of allowed channels (0 = any channel)
15
 * @param channel Output parameter for allocated channel number
16
 * @return DC1394_SUCCESS on success, error code on failure
17
 */
18
int dc1394_iso_allocate_channel(dc1394camera_t camera, long channels_allowed, IntPointer channel);
19

20
/**
21
 * Releases a previously allocated IEEE 1394 isochronous channel
22
 * @param camera Camera instance
23
 * @param channel Channel number to release
24
 * @return DC1394_SUCCESS on success, error code on failure
25
 */
26
int dc1394_iso_release_channel(dc1394camera_t camera, int channel);
27
```
28

29
**Usage Example:**
30

31
```java
32
import org.bytedeco.libdc1394.*;
33
import static org.bytedeco.libdc1394.global.dc1394.*;
34
import org.bytedeco.javacpp.IntPointer;
35

36
// Allocate any available channel
37
IntPointer channel = new IntPointer(1);
38
int err = dc1394_iso_allocate_channel(camera, 0, channel);
39
if (err != DC1394_SUCCESS) {
40
    dc1394_log_error("Failed to allocate ISO channel: " + err);
41
    return;
42
}
43

44
System.out.println("Allocated ISO channel: " + channel.get());
45

46
// Use channel for video transmission...
47

48
// Always release the channel when done
49
dc1394_iso_release_channel(camera, channel.get());
50
```
51

52
### Bandwidth Management
53

54
Manages IEEE 1394 isochronous bandwidth allocation for video streaming.
55

56
```java { .api }
57
/**
58
 * Allocates IEEE 1394 isochronous bandwidth units for video streaming
59
 * @param camera Camera instance
60
 * @param bandwidth_units Number of bandwidth units to allocate
61
 * @return DC1394_SUCCESS on success, error code on failure
62
 */
63
int dc1394_iso_allocate_bandwidth(dc1394camera_t camera, int bandwidth_units);
64

65
/**
66
 * Releases previously allocated IEEE 1394 isochronous bandwidth
67
 * @param camera Camera instance  
68
 * @param bandwidth_units Number of bandwidth units to release
69
 * @return DC1394_SUCCESS on success, error code on failure
70
 */
71
int dc1394_iso_release_bandwidth(dc1394camera_t camera, int bandwidth_units);
72
```
73

74
**Usage Example:**
75

76
```java
77
import org.bytedeco.libdc1394.*;
78
import static org.bytedeco.libdc1394.global.dc1394.*;
79

80
// Calculate required bandwidth for current video mode
81
IntPointer bandwidth = new IntPointer(1);
82
int err = dc1394_video_get_bandwidth_usage(camera, bandwidth);
83
if (err != DC1394_SUCCESS) {
84
    dc1394_log_error("Failed to get bandwidth usage: " + err);
85
    return;
86
}
87

88
// Allocate the required bandwidth
89
err = dc1394_iso_allocate_bandwidth(camera, bandwidth.get());
90
if (err != DC1394_SUCCESS) {
91
    dc1394_log_error("Failed to allocate bandwidth: " + err);
92
    return;
93
}
94

95
System.out.println("Allocated " + bandwidth.get() + " bandwidth units");
96

97
// Set up video transmission...
98

99
// Release bandwidth when done
100
dc1394_iso_release_bandwidth(camera, bandwidth.get());
101
```
102

103
### Resource Persistence and Cleanup
104

105
Controls resource persistence across application restarts and provides cleanup functionality.
106

107
```java { .api }
108
/**
109
 * Sets IEEE 1394 resources to persist across application restarts
110
 * Resources will remain allocated even if the application exits unexpectedly
111
 * @param camera Camera instance
112
 * @return DC1394_SUCCESS on success, error code on failure
113
 */
114
int dc1394_iso_set_persist(dc1394camera_t camera);
115

116
/**
117
 * Releases all IEEE 1394 resources (channels and bandwidth) allocated by this camera
118
 * Use this for cleanup when shutting down or in error conditions
119
 * @param camera Camera instance
120
 * @return DC1394_SUCCESS on success, error code on failure
121
 */
122
int dc1394_iso_release_all(dc1394camera_t camera);
123
```
124

125
**Usage Example:**
126

127
```java
128
import org.bytedeco.libdc1394.*;
129
import static org.bytedeco.libdc1394.global.dc1394.*;
130

131
// For critical applications, set resources to persist
132
int err = dc1394_iso_set_persist(camera);
133
if (err != DC1394_SUCCESS) {
134
    dc1394_log_warning("Could not set resource persistence: " + err);
135
}
136

137
// Allocate resources and perform video operations...
138

139
// In error handling or shutdown code, release all resources
140
err = dc1394_iso_release_all(camera);
141
if (err != DC1394_SUCCESS) {
142
    dc1394_log_error("Failed to release all ISO resources: " + err);
143
}
144
```
145

146
## Best Practices
147

148
### Resource Management Pattern
149

150
Always follow this pattern for robust resource management:
151

152
```java
153
import org.bytedeco.libdc1394.*;
154
import static org.bytedeco.libdc1394.global.dc1394.*;
155
import org.bytedeco.javacpp.IntPointer;
156

157
public class ISOResourceExample {
158
    private dc1394camera_t camera;
159
    private IntPointer channel = new IntPointer(1);
160
    private int allocatedBandwidth = 0;
161
    
162
    public boolean setupVideoStreaming() {
163
        try {
164
            // 1. Allocate channel
165
            int err = dc1394_iso_allocate_channel(camera, 0, channel);
166
            if (err != DC1394_SUCCESS) {
167
                dc1394_log_error("Channel allocation failed: " + err);
168
                return false;
169
            }
170
            
171
            // 2. Get required bandwidth
172
            IntPointer bandwidth = new IntPointer(1);
173
            err = dc1394_video_get_bandwidth_usage(camera, bandwidth);
174
            if (err != DC1394_SUCCESS) {
175
                dc1394_log_error("Bandwidth query failed: " + err);
176
                cleanup();
177
                return false;
178
            }
179
            
180
            // 3. Allocate bandwidth
181
            allocatedBandwidth = bandwidth.get();
182
            err = dc1394_iso_allocate_bandwidth(camera, allocatedBandwidth);
183
            if (err != DC1394_SUCCESS) {
184
                dc1394_log_error("Bandwidth allocation failed: " + err);
185
                cleanup();
186
                return false;
187
            }
188
            
189
            System.out.println("ISO resources allocated successfully");
190
            System.out.println("Channel: " + channel.get() + ", Bandwidth: " + allocatedBandwidth);
191
            return true;
192
            
193
        } catch (Exception e) {
194
            dc1394_log_error("Exception during resource allocation: " + e.getMessage());
195
            cleanup();
196
            return false;
197
        }
198
    }
199
    
200
    public void cleanup() {
201
        // Always clean up in reverse order of allocation
202
        if (allocatedBandwidth > 0) {
203
            dc1394_iso_release_bandwidth(camera, allocatedBandwidth);
204
            allocatedBandwidth = 0;
205
        }
206
        
207
        if (channel.get() >= 0) {
208
            dc1394_iso_release_channel(camera, channel.get());
209
            channel.put(-1);
210
        }
211
    }
212
}
213
```
214

215
### Multi-Camera Considerations
216

217
When working with multiple cameras, coordinate resource allocation:
218

219
```java
220
// For multi-camera setups, allocate resources for all cameras first
221
List<dc1394camera_t> cameras = // ... initialized cameras
222
List<IntPointer> channels = new ArrayList<>();
223
int totalBandwidth = 0;
224

225
// Calculate total bandwidth requirements
226
for (dc1394camera_t camera : cameras) {
227
    IntPointer bandwidth = new IntPointer(1);
228
    dc1394_video_get_bandwidth_usage(camera, bandwidth);
229
    totalBandwidth += bandwidth.get();
230
}
231

232
// Check if total bandwidth is available before proceeding
233
if (totalBandwidth > MAX_AVAILABLE_BANDWIDTH) {
234
    dc1394_log_error("Insufficient bandwidth for all cameras: " + totalBandwidth);
235
    return false;
236
}
237

238
// Allocate resources for each camera
239
for (dc1394camera_t camera : cameras) {
240
    IntPointer channel = new IntPointer(1);
241
    dc1394_iso_allocate_channel(camera, 0, channel);
242
    channels.add(channel);
243
    
244
    IntPointer bandwidth = new IntPointer(1);
245
    dc1394_video_get_bandwidth_usage(camera, bandwidth);
246
    dc1394_iso_allocate_bandwidth(camera, bandwidth.get());
247
}
248
```
249

250
## Error Handling
251

252
ISO resource functions return standard libdc1394 error codes:
253

254
```java
255
int err = dc1394_iso_allocate_channel(camera, 0, channel);
256
switch (err) {
257
    case DC1394_SUCCESS:
258
        System.out.println("Channel allocated successfully");
259
        break;
260
    case DC1394_FAILURE:
261
        dc1394_log_error("General failure in channel allocation");
262
        break;
263
    case DC1394_MEMORY_ALLOCATION_FAILURE:
264
        dc1394_log_error("Out of memory during channel allocation");
265
        break;
266
    default:
267
        dc1394_log_error("Unexpected error in channel allocation: " + err);
268
        break;
269
}
270
```
271

272
Use `dc1394_iso_release_all()` in exception handlers to ensure cleanup:
273

274
```java
275
try {
276
    // ISO resource operations...
277
} catch (Exception e) {
278
    dc1394_log_error("Exception occurred: " + e.getMessage());
279
    dc1394_iso_release_all(camera);  // Emergency cleanup
280
    throw e;
281
}
282
```