oiio-sys 0.4.1

Rust sys bindings for OpenImageIO https://github.com/AcademySoftwareFoundation/OpenImageIO
Documentation
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
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
#include "ffi_deepdata.h"
#include <OpenImageIO/span.h>

namespace oiio {

// DeepData allocates its sample storage lazily: set_samples records the
// count, and the first write (or a capacity change) does the real
// m_data.resize with no try/catch of its own. Every shim below that can
// reach that resize is wrapped noexcept by cxx, so an escaping bad_alloc
// would be std::terminate -- the same hazard deepdata_init_from_spec already
// guards for the pixel axis. This helper catches and reports for the
// sample axis.
template<typename Mutation>
static bool
guarded_deep_mutation(rust::String& error, Mutation&& mutation)
{
    error = rust::String();
    try {
        mutation();
        return true;
    } catch (const std::exception& exception) {
        const std::string recorded = exception.what();
        error = rust::String::lossy(
            recorded.empty() ? "OpenImageIO could not allocate the deep samples"
                             : recorded.c_str());
        return false;
    }
}

std::unique_ptr<DeepData>
deepdata_default()
{
    return std::make_unique<DeepData>();
}

std::unique_ptr<DeepData>
deepdata_new_from_spec(const ImageSpec& spec)
{
    return std::make_unique<DeepData>(spec);
}

std::unique_ptr<DeepData>
deepdata_clone(const DeepData& src)
{
    return std::make_unique<DeepData>(src);
}

std::unique_ptr<DeepData>
deepdata_clone_with_channeltypes(const DeepData& src,
                                 rust::Slice<const TypeDesc> channeltypes)
{
    OIIO::cspan<TypeDesc> c_channeltypes(channeltypes.data(),
                                         channeltypes.size());
    return std::make_unique<DeepData>(src, c_channeltypes);
}

void
deepdata_clear(DeepData& deepdata)
{
    deepdata.clear();
}

void
deepdata_free(DeepData& deepdata)
{
    deepdata.free();
}

void
deepdata_init(DeepData& deepdata, int64_t npix, int nchan,
              rust::Slice<const TypeDesc> channeltypes,
              rust::Slice<const rust::String> channelnames)
{
    OIIO::cspan<TypeDesc> c_channeltypes(channeltypes.data(),
                                         channeltypes.size());
    std::vector<std::string> channelnames_vec;
    channelnames_vec.reserve(channelnames.size());

    for (auto& s : channelnames) {
        channelnames_vec.push_back(std::string(s));
    }

    OIIO::cspan<std::string> c_channelnames(channelnames_vec.data(),
                                            channelnames_vec.size());
    deepdata.init(npix, nchan, c_channeltypes, c_channelnames);
}

bool
deepdata_init_from_spec(DeepData& deepdata, const ImageSpec& spec,
                        rust::String& error)
{
    // DeepData::init resizes three per-pixel vectors with no try/catch, so a
    // deep spec whose pixel count is within the i32 cap but still too large for
    // the machine throws bad_alloc straight out. This shim is noexcept, so that
    // would be std::terminate. Catch it and report, as the flat path does.
    error = rust::String();
    try {
        deepdata.init(spec);
        return true;
    } catch (const std::exception& exception) {
        const std::string recorded = exception.what();
        error = rust::String::lossy(
            recorded.empty() ? "OpenImageIO could not allocate the deep image"
                             : recorded.c_str());
        return false;
    }
}

bool
deepdata_initialized(const DeepData& deepdata)
{
    return deepdata.initialized();
}

bool
deepdata_allocated(const DeepData& deepdata)
{
    return deepdata.allocated();
}

int64_t
deepdata_pixels(const DeepData& deepdata)
{
    return deepdata.pixels();
}

int
deepdata_channels(const DeepData& deepdata)
{
    return deepdata.channels();
}

int
deepdata_z_channel(const DeepData& deepdata)
{
    return deepdata.Z_channel();
}

int
deepdata_z_back_channel(const DeepData& deepdata)
{
    return deepdata.Zback_channel();
}

int
deepdata_a_channel(const DeepData& deepdata)
{
    return deepdata.A_channel();
}

int
deepdata_ar_channel(const DeepData& deepdata)
{
    return deepdata.AR_channel();
}

int
deepdata_ag_channel(const DeepData& deepdata)
{
    return deepdata.AG_channel();
}

int
deepdata_ab_channel(const DeepData& deepdata)
{
    return deepdata.AB_channel();
}

// channelname() returns a string_view over bytes copied verbatim from the
// file: OpenEXR checks channel names only for null-termination and length,
// never encoding. A borrowed rust::Str would validate UTF-8 in a throwing
// constructor inside a noexcept wrapper -- reading a deep file with one high
// byte in a channel name would be std::terminate -- and rust::Str has no
// lossy form, so the name is returned owned and lossy like the error
// strings. (An earlier version borrowed, which also risked pointing into a
// destroyed temporary via the std::string constructor.)
rust::String
deepdata_channelname(const DeepData& deepdata, int c)
{
    const OIIO::string_view name = deepdata.channelname(c);
    return rust::String::lossy(name.data(), name.size());
}

TypeDesc
deepdata_channeltype(const DeepData& deepdata, int c)
{
    return deepdata.channeltype(c);
}

size_t
deepdata_channelsize(const DeepData& deepdata, int c)
{
    return deepdata.channelsize(c);
}

size_t
deepdata_samplesize(const DeepData& deepdata)
{
    return deepdata.samplesize();
}

bool
deepdata_same_channeltypes(const DeepData& deepdata, const DeepData& other)
{
    return deepdata.same_channeltypes(other);
}

int
deepdata_samples(const DeepData& deepdata, int64_t pixel)
{
    return deepdata.samples(pixel);
}

bool
deepdata_set_samples(DeepData& deepdata, int64_t pixel, int samps,
                     rust::String& error)
{
    // On an already-allocated DeepData this becomes an insert, whose
    // capacity growth resizes the sample storage; see the helper.
    return guarded_deep_mutation(error,
                                 [&] { deepdata.set_samples(pixel, samps); });
}

bool
deepdata_set_all_samples(DeepData& deepdata,
                         rust::Slice<const unsigned int> samples,
                         rust::String& error)
{
    return guarded_deep_mutation(error, [&] {
        deepdata.set_all_samples(
            OIIO::cspan<unsigned int>(samples.data(), samples.size()));
    });
}

bool
deepdata_set_capacity(DeepData& deepdata, int64_t pixel, int samps,
                      rust::String& error)
{
    return guarded_deep_mutation(error,
                                 [&] { deepdata.set_capacity(pixel, samps); });
}

int
deepdata_capacity(const DeepData& deepdata, int64_t pixel)
{
    return deepdata.capacity(pixel);
}

bool
deepdata_insert_samples(DeepData& deepdata, int64_t pixel, int samplepos, int n,
                        rust::String& error)
{
    // Unlike samples()/capacity()/data_ptr()/deep_value(), which range-check
    // the pixel index and return 0/NULL, insert_samples and erase_samples index
    // m_nsamples[pixel] and m_capacity[pixel] with no check of their own, so an
    // out-of-range pixel is a heap read and write past those vectors. Bound it
    // here, which keeps these two callable safely like their guarded siblings.
    error = rust::String();
    if (pixel < 0 || pixel >= deepdata.pixels())
        return true;
    // Growth can reach set_capacity's storage resize; see the helper.
    return guarded_deep_mutation(
        error, [&] { deepdata.insert_samples(pixel, samplepos, n); });
}

void
deepdata_erase_samples(DeepData& deepdata, int64_t pixel, int samplepos, int n)
{
    if (pixel < 0 || pixel >= deepdata.pixels())
        return;
    deepdata.erase_samples(pixel, samplepos, n);
}

float
deepdata_deep_value(const DeepData& deepdata, int64_t pixel, int channel,
                    int sample)
{
    return deepdata.deep_value(pixel, channel, sample);
}

uint32_t
deepdata_deep_value_uint(const DeepData& deepdata, int64_t pixel, int channel,
                         int sample)
{
    return deepdata.deep_value_uint(pixel, channel, sample);
}

bool
deepdata_set_deep_value(DeepData& deepdata, int64_t pixel, int channel,
                        int sample, float value, rust::String& error)
{
    // The first write is what performs the deferred sample allocation.
    return guarded_deep_mutation(error, [&] {
        deepdata.set_deep_value(pixel, channel, sample, value);
    });
}

bool
deepdata_set_deep_value_uint(DeepData& deepdata, int64_t pixel, int channel,
                             int sample, uint32_t value, rust::String& error)
{
    return guarded_deep_mutation(error, [&] {
        deepdata.set_deep_value(pixel, channel, sample, value);
    });
}

uint8_t*
deepdata_mut_data_ptr(DeepData& deepdata, int64_t pixel, int channel,
                      int sample)
{
    // The mutable data_ptr performs the deferred sample allocation, so it can
    // throw bad_alloc; null already means "nothing at this address", and a
    // failed allocation is exactly that.
    try {
        return (uint8_t*)deepdata.data_ptr(pixel, channel, sample);
    } catch (const std::exception&) {
        return nullptr;
    }
}

const uint8_t*
deepdata_data_ptr(const DeepData& deepdata, int64_t pixel, int channel,
                  int sample)
{
    return (uint8_t*)deepdata.data_ptr(pixel, channel, sample);
}

rust::Slice<const TypeDesc>
deepdata_all_channeltypes(const DeepData& deepdata)
{
    OIIO::cspan<TypeDesc> c_all_channeltypes = deepdata.all_channeltypes();
    return rust::Slice<const TypeDesc>(c_all_channeltypes.data(),
                                       c_all_channeltypes.size());
}

rust::Slice<const unsigned int>
deepdata_all_samples(const DeepData& deepdata)
{
    OIIO::cspan<unsigned int> c_all_samples = deepdata.all_samples();
    return rust::Slice<const unsigned int>(c_all_samples.data(),
                                           c_all_samples.size());
}

rust ::Slice<const char>
deepdata_all_data(const DeepData& deepdata)
{
    // all_data also performs the deferred allocation despite being const;
    // an empty slice is the honest answer when it cannot be made.
    try {
        OIIO::cspan<char> c_all_data = deepdata.all_data();
        return rust::Slice<const char>(c_all_data.data(), c_all_data.size());
    } catch (const std::exception&) {
        return rust::Slice<const char>();
    }
}

size_t
deepdata_get_pointers(const DeepData& deepdata, rust::Slice<uint8_t*> pointers)
{
    // DeepData::get_pointers resizes the vector it is given to
    // pixels() * channels() and fills it, so the vector is an out parameter
    // rather than an in-out one. Copying the caller's slice in was pointless
    // and, worse, nothing was ever copied back: the function looked like an
    // out-parameter fill and was a guaranteed no-op.
    //
    // It also performs the deferred sample allocation, so it can throw; zero
    // pointers is the honest answer then, and distinguishable, since a deep
    // image with pixels always produces at least one entry.
    std::vector<void*> c_pointers;
    try {
        deepdata.get_pointers(c_pointers);
    } catch (const std::exception&) {
        return 0;
    }

    const size_t available = c_pointers.size();
    const size_t copied    = std::min(available, pointers.size());
    for (size_t i = 0; i < copied; ++i)
        pointers[i] = static_cast<uint8_t*>(c_pointers[i]);
    // The number OpenImageIO produced, so a caller given a short slice can
    // tell it was truncated rather than assume it saw everything.
    return available;
}

bool
deepdata_copy_deep_sample(DeepData& deepdata, int64_t pixel, int sample,
                          const DeepData& src, int64_t srcpixel, int srcsample)
{
    // Copying grows the destination pixel, which can reach the storage
    // resize; false already means the copy did not happen.
    try {
        return deepdata.copy_deep_sample(pixel, sample, src, srcpixel,
                                         srcsample);
    } catch (const std::exception&) {
        return false;
    }
}

bool
deepdata_copy_deep_pixel(DeepData& deepdata, int64_t pixel, const DeepData& src,
                         int64_t srcpixel)
{
    // Sizes the destination pixel with set_samples, which can reach the
    // storage resize; false already means the copy did not happen.
    try {
        return deepdata.copy_deep_pixel(pixel, src, srcpixel);
    } catch (const std::exception&) {
        return false;
    }
}

bool
deepdata_split(DeepData& deepdata, int64_t pixel, float depth)
{
    // Splitting inserts samples, which can grow the pixel's capacity; false
    // already means nothing was split.
    try {
        return deepdata.split(pixel, depth);
    } catch (const std::exception&) {
        return false;
    }
}

void
deepdata_sort(DeepData& deepdata, int64_t pixel)
{
    // Sorting builds a per-pixel temporary, so under memory pressure it can
    // throw; the pixel is then simply left unsorted, which is the state the
    // caller already had.
    try {
        deepdata.sort(pixel);
    } catch (const std::exception&) {
    }
}

void
deepdata_merge_overlaps(DeepData& deepdata, int64_t pixel)
{
    deepdata.merge_overlaps(pixel);
}

void
deepdata_merge_deep_pixels(DeepData& deepdata, int64_t pixel,
                           const DeepData& src, int srcpixel)
{
    // Merging grows the destination pixel, which can reach the storage
    // resize; on failure the pixel keeps its previous samples.
    try {
        deepdata.merge_deep_pixels(pixel, src, srcpixel);
    } catch (const std::exception&) {
    }
}

float
deepdata_opaque_z(const DeepData& deepdata, int64_t pixel)
{
    return deepdata.opaque_z(pixel);
}

void
deepdata_occlusion_cull(DeepData& deepdata, int64_t pixel)
{
    deepdata.occlusion_cull(pixel);
}
}  // namespace oiio