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
//! Safe Rust bindings to OpenImageIO 3.1 and 3.2.
//!
//! Read and write every format OpenImageIO supports, in `u8`, `u16`,
//! [`f16`](struct@f16) or `f32`. Dimensions, regions and buffer lengths are
//! all checked before anything crosses into C++, so a mistake is a typed
//! error rather than undefined behaviour.
//!
//! # Reading
//!
//! ```no_run
//! use oiio::ImageInput;
//! use std::path::Path;
//!
//! # fn main() -> oiio::Result<()> {
//! let mut input = ImageInput::from_path(Path::new("image.exr"))?;
//! let spec = input.image_spec()?;
//! let mut pixels = vec![0.0_f32; spec.element_count()?];
//! input.read_image_into(&mut pixels)?;
//! input.close()?;
//! # Ok(())
//! # }
//! ```
//!
//! Part of an image is a [`Roi`], which selects pixels *and* channels, so
//! reading one AOV out of a 38-channel EXR does not decode the other 37:
//!
//! ```no_run
//! # use oiio::ImageInput;
//! # use std::path::Path;
//! # fn main() -> oiio::Result<()> {
//! # let mut input = ImageInput::from_path(Path::new("image.exr"))?;
//! # let spec = input.image_spec()?;
//! let roi = spec.data_window()?.with_y(0..64)?.with_channels(0..3)?;
//! let mut pixels = vec![0.0_f32; roi.element_count()?];
//! input.read_region_into(roi, &mut pixels)?;
//! # Ok(())
//! # }
//! ```
//!
//! # What else is here
//!
//! - [`ImageOutput`] writes files, whole or in scanline and tile pieces,
//! with subimages, mip levels and multi-part files.
//! - [`ImageCache`] serves regions from many files under a memory budget,
//! with [`ImageHandle`] to skip repeated name lookups and [`TileGuard`] to
//! borrow one tile at a time.
//! - [`ImageBuf`] holds an image in memory and [`algo`] operates on it:
//! arithmetic, compositing, resizing, channel shuffling and colour
//! conversion.
//! - [`DeepImage`] reads deep files, where each pixel holds a list of
//! samples rather than one value.
//! - [`ColorConfig`] reports which colour spaces the active OpenColorIO
//! configuration defines, so conversions need not guess at names.
//! - [`make_texture`] writes the tiled, MIP-mapped files a renderer wants,
//! and [`TextureSystem`] does the filtered lookups into them.
//! - Neither reading nor writing needs the filesystem:
//! [`ImageInput::from_memory`] and [`ImageOutput::to_memory`] work on
//! buffers.
//!
//! # Metadata
//!
//! Attributes arrive as [`AttributeValue`]. Integers, floats and strings are
//! modelled directly; everything else keeps the bytes OpenImageIO stored, so
//! an attribute this crate does not understand still survives being read from
//! one image and written to another.
use oiio_sys as sys;
/// Give a fieldless enum one table of names, and derive everything from it.
///
/// `name` is the single source of truth: [`Display`](std::fmt::Display)
/// prints it and [`FromStr`](std::str::FromStr) parses it, case
/// insensitively, so a value can come from a command line or a
/// configuration file. The names are OpenImageIO's own wherever OpenImageIO
/// has one, so a string written for `oiiotool` means the same thing here.
pub use AttributeValue;
pub use ColorConfig;
pub use ;
pub use ;
pub use f16;
// The README's samples are written as Rust, but nothing compiled them: the
// file is not included anywhere, so rustdoc never saw it and a sample could
// drift from the API with every release and still look right. This item
// exists only under `cfg(doctest)`, so the blocks become doctests without
// appearing in the rendered documentation.
;
pub use ;
pub use ;
pub use ImageSpec;
pub use ;
pub use Pixel;
pub use PixelFormat;
pub use Roi;
pub use ;
/// Backwards-compatible name for errors returned by `ImageInput`.
pub type ImageInputIoError = Error;
pub