use std::ops::Range;
use std::path::{Path, PathBuf};
use crate::image_spec::element_count;
use crate::{path_to_utf8, pixel, sys, DeepImage, Error, ImageSpec, Pixel, Result, Roi};
pub struct ImageInput {
inner: cxx::UniquePtr<sys::imageio::ImageInput>,
_proxy: Option<cxx::UniquePtr<sys::filesystem::IOProxy>>,
_bytes: Option<Vec<u8>>,
}
unsafe impl Send for ImageInput {}
impl ImageInput {
pub fn from_path_with_config(image_path: &Path, config: &ImageSpec) -> Result<Self> {
let image_path_str = path_to_utf8(image_path)?;
let native = config.to_sys()?;
let Some(native) = native.as_ref() else {
return Err(Error::InvalidImageSpec(
"OpenImageIO could not allocate the configuration hints".to_owned(),
));
};
match sys::imageio::imageinput_open_with_config(image_path_str, native) {
Ok(imageinput) if !imageinput.is_null() => Ok(Self {
inner: imageinput,
_proxy: None,
_bytes: None,
}),
Ok(_) => {
let message = if sys::imageio::has_error() {
sys::imageio::get_error(true)
} else {
"OpenImageIO did not provide an error message".to_owned()
};
Err(Error::OpenImage {
path: image_path.to_path_buf(),
message,
})
}
Err(exception) => Err(Error::OpenImage {
path: image_path.to_path_buf(),
message: exception.what().to_owned(),
}),
}
}
pub fn from_path(image_path: &Path) -> Result<Self> {
let image_path_str = path_to_utf8(image_path)?;
match sys::imageio::imageinput_open_without_config(image_path_str) {
Ok(imageinput) if !imageinput.is_null() => Ok(Self {
inner: imageinput,
_proxy: None,
_bytes: None,
}),
Ok(_) => {
let message = if sys::imageio::has_error() {
sys::imageio::get_error(true)
} else {
"OpenImageIO did not provide an error message".to_owned()
};
Err(Error::OpenImage {
path: image_path.to_path_buf(),
message,
})
}
Err(error) => Err(Error::OpenImage {
path: image_path.to_path_buf(),
message: error.to_string(),
}),
}
}
pub fn from_memory(name_hint: &str, bytes: Vec<u8>) -> Result<Self> {
let mut proxy = unsafe { sys::filesystem::ioproxy_memreader_new(&bytes) };
let Some(proxy_ref) = proxy.as_mut() else {
return Err(Self::memory_error(
name_hint,
"OpenImageIO could not allocate a memory proxy".to_owned(),
));
};
let inner = unsafe {
let proxy_ptr = proxy_ref.get_unchecked_mut() as *mut sys::filesystem::IOProxy;
sys::imageio::imageinput_open_with_ioproxy(name_hint, proxy_ptr)
};
if inner.is_null() {
return Err(Self::memory_error(name_hint, global_error()));
}
Ok(Self {
inner,
_proxy: Some(proxy),
_bytes: Some(bytes),
})
}
pub fn format_name(&self) -> &str {
sys::imageio::imageinput_format_name(self.inner())
}
fn memory_error(name_hint: &str, message: String) -> Error {
Error::OpenImage {
path: PathBuf::from(name_hint),
message: if message.is_empty() {
"OpenImageIO did not provide an error message".to_owned()
} else {
message
},
}
}
pub fn image_spec(&self) -> Result<ImageSpec> {
ImageSpec::from_sys(sys::imageio::imageinput_spec(self.inner()))
}
pub fn image_spec_at(&mut self, subimage: u32, mip_level: u32) -> Result<ImageSpec> {
let subimage_i32 = level_index(subimage)?;
let mip_level_i32 = level_index(mip_level)?;
let spec = sys::imageio::imageinput_spec_subimage_miplevel(
self.inner_mut(),
subimage_i32,
mip_level_i32,
);
let Some(spec) = spec.as_ref() else {
let _ = sys::imageio::imageinput_geterror(self.inner_mut());
return Err(Error::InvalidImageLevel {
subimage,
mip_level,
});
};
if !sys::imageio::imagespec_valid(spec) {
let _ = sys::imageio::imageinput_geterror(self.inner_mut());
return Err(Error::InvalidImageLevel {
subimage,
mip_level,
});
}
ImageSpec::from_sys(spec)
}
pub fn read_image_into<T: Pixel>(&mut self, pixels: &mut [T]) -> Result<()> {
self.read_image_into_at(0, 0, pixels)
}
pub fn read_image_into_at<T: Pixel>(
&mut self,
subimage: u32,
mip_level: u32,
pixels: &mut [T],
) -> Result<()> {
let spec = self.image_spec_at(subimage, mip_level)?;
if spec.is_deep() {
return Err(Error::UnsupportedDeepImage);
}
let expected = spec.element_count()?;
validate_buffer_len(expected, pixels.len())?;
let channel_end = i32::try_from(spec.channel_count()).map_err(|_| {
Error::InvalidImageSpec("channel count does not fit in an i32".to_owned())
})?;
let succeeded = unsafe {
sys::imageio::imageinput_read_image_span(
self.inner_mut(),
level_index(subimage)?,
level_index(mip_level)?,
0,
channel_end,
pixel::type_desc::<T>(),
pixel::as_bytes_mut(pixels),
)
};
if succeeded {
Ok(())
} else {
Err(self.take_error("read image"))
}
}
pub fn read_region_into<T: Pixel>(&mut self, roi: Roi, pixels: &mut [T]) -> Result<()> {
self.read_region_into_at(0, 0, roi, pixels)
}
pub fn read_region_into_at<T: Pixel>(
&mut self,
subimage: u32,
mip_level: u32,
roi: Roi,
pixels: &mut [T],
) -> Result<()> {
let spec = self.image_spec_at(subimage, mip_level)?;
if spec.is_deep() {
return Err(Error::UnsupportedDeepImage);
}
roi.validate_within(&spec)?;
validate_buffer_len(roi.element_count()?, pixels.len())?;
let subimage_i32 = level_index(subimage)?;
let mip_level_i32 = level_index(mip_level)?;
let channels = roi.channels();
let channel_begin = level_index(channels.start)?;
let channel_end = level_index(channels.end)?;
let origin = spec.origin();
let dimensions = spec.dimensions();
let succeeded = if spec.is_tiled() {
let [tile_width, tile_height, tile_depth] = spec.tile_dimensions();
validate_tile_alignment("x", &roi.x(), origin[0], dimensions[0], tile_width)?;
validate_tile_alignment("y", &roi.y(), origin[1], dimensions[1], tile_height)?;
validate_tile_alignment("z", &roi.z(), origin[2], dimensions[2], tile_depth.max(1))?;
unsafe {
sys::imageio::imageinput_read_tiles_span(
self.inner_mut(),
subimage_i32,
mip_level_i32,
roi.x().start,
roi.x().end,
roi.y().start,
roi.y().end,
roi.z().start,
roi.z().end,
channel_begin,
channel_end,
pixel::type_desc::<T>(),
pixel::as_bytes_mut(pixels),
)
}
} else {
let width_end = i64::from(origin[0]) + i64::from(dimensions[0]);
if i64::from(roi.x().start) != i64::from(origin[0])
|| i64::from(roi.x().end) != width_end
{
return Err(Error::InvalidRegion {
axis: "x",
message: format!(
"a scanline image is read a whole row at a time, so the x range must \
cover the full width {}..{width_end}",
origin[0]
),
});
}
if roi.depth() != 1 {
return Err(Error::InvalidRegion {
axis: "z",
message: "a scanline image is read one z slice at a time".to_owned(),
});
}
unsafe {
sys::imageio::imageinput_read_scanlines_span(
self.inner_mut(),
subimage_i32,
mip_level_i32,
roi.y().start,
roi.y().end,
roi.z().start,
channel_begin,
channel_end,
pixel::type_desc::<T>(),
pixel::as_bytes_mut(pixels),
)
}
};
if succeeded {
Ok(())
} else {
Err(self.take_error("read region"))
}
}
pub fn read_deep_image(&mut self) -> Result<DeepImage> {
self.read_deep_image_at(0, 0)
}
pub fn read_deep_image_at(&mut self, subimage: u32, mip_level: u32) -> Result<DeepImage> {
let spec = self.image_spec_at(subimage, mip_level)?;
if !spec.is_deep() {
return Err(Error::operation(
"read deep image",
"this image is not deep; use read_image_into".to_owned(),
));
}
let mut deep = sys::deepdata::deepdata_default();
let Some(pinned) = deep.as_mut() else {
return Err(Error::operation(
"read deep image",
"OpenImageIO could not allocate deep data".to_owned(),
));
};
let mut error = String::new();
let succeeded = sys::imageio::imageinput_read_native_deep_image(
self.inner_mut(),
level_index(subimage)?,
level_index(mip_level)?,
pinned,
&mut error,
);
if !succeeded {
if !error.is_empty() {
return Err(Error::operation("read deep image", error));
}
return Err(self.take_error("read deep image"));
}
DeepImage::from_parts(deep, &spec)
}
pub fn read_native_image(&mut self) -> Result<Vec<u8>> {
self.read_native_image_at(0, 0)
}
pub fn read_native_image_at(&mut self, subimage: u32, mip_level: u32) -> Result<Vec<u8>> {
const OPERATION: &str = "read native image";
let spec = self.image_spec_at(subimage, mip_level)?;
if spec.is_deep() {
return Err(Error::UnsupportedDeepImage);
}
let expected = spec
.pixel_count()?
.checked_mul(spec.native_pixel_bytes()?)
.ok_or_else(|| Error::InvalidImageSpec("the image's byte size overflows".to_owned()))?;
let mut bytes = vec![0_u8; expected];
let mut error = String::new();
let succeeded = sys::imageio::imageinput_read_native_image_bytes(
self.inner_mut(),
level_index(subimage)?,
level_index(mip_level)?,
&mut bytes,
&mut error,
);
if succeeded {
Ok(bytes)
} else {
Err(Error::operation(OPERATION, error))
}
}
pub fn read_deep_scanlines_at(
&mut self,
subimage: u32,
mip_level: u32,
y: Range<i32>,
) -> Result<DeepImage> {
const OPERATION: &str = "read deep scanlines";
let spec = self.require_deep_spec(OPERATION, subimage, mip_level)?;
if spec.is_tiled() {
return Err(Error::InvalidImageSpec(
"this file is tiled; use read_deep_tiles_at".to_owned(),
));
}
if spec.dimensions()[2] != 1 {
return Err(Error::InvalidImageSpec(
"scanline reads require a two-dimensional image".to_owned(),
));
}
let rows = validate_axis("y", &y, spec.origin()[1], spec.dimensions()[1])?;
let mut deep = sys::deepdata::deepdata_default();
let Some(pinned) = deep.as_mut() else {
return Err(Error::operation(
OPERATION,
"OpenImageIO could not allocate deep data".to_owned(),
));
};
let mut error = String::new();
let succeeded = sys::imageio::imageinput_read_native_deep_scanlines(
self.inner_mut(),
level_index(subimage)?,
level_index(mip_level)?,
y.start,
y.end,
0,
0,
spec.channel_count() as i32,
pinned,
&mut error,
);
if !succeeded {
if !error.is_empty() {
return Err(Error::operation(OPERATION, error));
}
return Err(self.take_error(OPERATION));
}
let band = ImageSpec::new(
spec.dimensions()[0],
rows,
spec.channel_count(),
spec.format(),
)?
.with_origin([spec.origin()[0], y.start, spec.origin()[2]]);
DeepImage::from_parts(deep, &band)
}
pub fn read_deep_tiles_at(
&mut self,
subimage: u32,
mip_level: u32,
x: Range<i32>,
y: Range<i32>,
z: Range<i32>,
) -> Result<DeepImage> {
const OPERATION: &str = "read deep tiles";
let spec = self.require_deep_spec(OPERATION, subimage, mip_level)?;
if !spec.is_tiled() {
return Err(Error::InvalidImageSpec(
"tile reads require a tiled file; use read_deep_scanlines_at".to_owned(),
));
}
let [tile_width, tile_height, tile_depth] = spec.tile_dimensions();
let origin = spec.origin();
let dimensions = spec.dimensions();
let width = validate_axis("x", &x, origin[0], dimensions[0])?;
let height = validate_axis("y", &y, origin[1], dimensions[1])?;
let depth = validate_axis("z", &z, origin[2], dimensions[2])?;
validate_tile_alignment("x", &x, origin[0], dimensions[0], tile_width)?;
validate_tile_alignment("y", &y, origin[1], dimensions[1], tile_height)?;
validate_tile_alignment("z", &z, origin[2], dimensions[2], tile_depth.max(1))?;
let mut deep = sys::deepdata::deepdata_default();
let Some(pinned) = deep.as_mut() else {
return Err(Error::operation(
OPERATION,
"OpenImageIO could not allocate deep data".to_owned(),
));
};
let mut error = String::new();
let succeeded = sys::imageio::imageinput_read_native_deep_tiles(
self.inner_mut(),
level_index(subimage)?,
level_index(mip_level)?,
x.start,
x.end,
y.start,
y.end,
z.start,
z.end,
0,
spec.channel_count() as i32,
pinned,
&mut error,
);
if !succeeded {
if !error.is_empty() {
return Err(Error::operation(OPERATION, error));
}
return Err(self.take_error(OPERATION));
}
let band = ImageSpec::new(width, height, spec.channel_count(), spec.format())?
.with_depth(depth)?
.with_origin([x.start, y.start, z.start]);
DeepImage::from_parts(deep, &band)
}
fn require_deep_spec(
&mut self,
operation: &'static str,
subimage: u32,
mip_level: u32,
) -> Result<ImageSpec> {
let spec = self.image_spec_at(subimage, mip_level)?;
if !spec.is_deep() {
return Err(Error::operation(
operation,
"this image is not deep; use read_image_into".to_owned(),
));
}
Ok(spec)
}
pub fn close(mut self) -> Result<()> {
if sys::imageio::imageinput_close(self.inner_mut()) {
Ok(())
} else {
Err(self.take_error("close image"))
}
}
pub fn threads(&self) -> i32 {
sys::imageio::imageinput_threads(self.inner())
}
pub fn set_threads(&mut self, threads: i32) {
sys::imageio::imageinput_set_threads(self.inner_mut(), threads);
}
fn inner(&self) -> &sys::imageio::ImageInput {
self.inner
.as_ref()
.expect("ImageInput invariant violated: null native pointer")
}
pub fn supports(&self, feature: &str) -> bool {
sys::imageio::imageinput_supports(self.inner(), feature)
}
pub fn is_valid_file(&self, image_path: &Path) -> Result<bool> {
let filename = path_to_utf8(image_path)?;
Ok(sys::imageio::imageinput_valid_file(self.inner(), filename))
}
pub(crate) fn native_mut(&mut self) -> std::pin::Pin<&mut sys::imageio::ImageInput> {
self.inner_mut()
}
fn inner_mut(&mut self) -> std::pin::Pin<&mut sys::imageio::ImageInput> {
self.inner
.as_mut()
.expect("ImageInput invariant violated: null native pointer")
}
fn take_error(&mut self, operation: &'static str) -> Error {
Error::operation(
operation,
sys::imageio::imageinput_geterror(self.inner_mut()),
)
}
}
pub struct ImageOutput {
inner: cxx::UniquePtr<sys::imageio::ImageOutput>,
path: PathBuf,
spec: ImageSpec,
next_scanline: i32,
proxy: Option<cxx::UniquePtr<sys::filesystem::IOProxy>>,
}
unsafe impl Send for ImageOutput {}
impl ImageOutput {
fn adopt_open_spec(&mut self, fallback: &ImageSpec) {
self.spec = ImageSpec::from_sys(sys::imageio::imageoutput_spec(self.inner()))
.unwrap_or_else(|_| fallback.clone());
self.next_scanline = self.spec.origin()[1];
}
pub fn create(image_path: &Path, spec: &ImageSpec) -> Result<Self> {
let mut output = Self::open_plugin(image_path)?;
let native_spec = spec.to_sys()?;
Self::open_native(
output.inner_mut(),
path_to_utf8(image_path)?,
&native_spec,
sys::imageio::OpenMode::Create,
)
.map_err(|message| Error::OpenImage {
path: image_path.to_path_buf(),
message,
})?;
output.path = image_path.to_path_buf();
output.adopt_open_spec(spec);
Ok(output)
}
pub fn create_multi_subimage(image_path: &Path, specs: &[ImageSpec]) -> Result<Self> {
let Some(first) = specs.first() else {
return Err(Error::InvalidImageSpec(
"a multi-part file needs at least one subimage".to_owned(),
));
};
let mut native_specs = sys::imageio::imagespec_vector_new();
for spec in specs {
let native_spec = spec.to_sys()?;
let (Some(list), Some(native_spec)) = (native_specs.as_mut(), native_spec.as_ref())
else {
return Err(Error::InvalidImageSpec(
"OpenImageIO could not allocate an image specification".to_owned(),
));
};
sys::imageio::imagespec_vector_push(list, native_spec);
}
let mut output = Self::open_plugin(image_path)?;
let path_str = path_to_utf8(image_path)?;
let opened =
sys::imageio::imageoutput_open_specs(output.inner_mut(), path_str, &native_specs);
if !opened {
let message = sys::imageio::imageoutput_geterror(output.inner(), true);
return Err(Error::OpenImage {
path: image_path.to_path_buf(),
message: if message.is_empty() {
"OpenImageIO did not provide an error message".to_owned()
} else {
message
},
});
}
output.path = image_path.to_path_buf();
output.adopt_open_spec(first);
Ok(output)
}
pub fn to_memory(name_hint: &str, spec: &ImageSpec) -> Result<Self> {
let mut proxy = sys::filesystem::ioproxy_vecoutput_new();
let Some(proxy_ref) = proxy.as_mut() else {
return Err(Error::CreateImage {
path: PathBuf::from(name_hint),
message: "OpenImageIO could not allocate a memory proxy".to_owned(),
});
};
let inner = unsafe {
let proxy_ptr = proxy_ref.get_unchecked_mut() as *mut sys::filesystem::IOProxy;
sys::imageio::imageoutput_create(name_hint, proxy_ptr, "")
};
if inner.is_null() {
return Err(Error::CreateImage {
path: PathBuf::from(name_hint),
message: global_error(),
});
}
let mut output = Self {
inner,
path: PathBuf::from(name_hint),
spec: spec.clone(),
next_scanline: spec.origin()[1],
proxy: Some(proxy),
};
if !output.supports("ioproxy") {
return Err(Error::CreateImage {
path: PathBuf::from(name_hint),
message: format!("the {} writer cannot write to memory", output.format_name()),
});
}
let native_spec = spec.to_sys()?;
Self::open_native(
output.inner_mut(),
name_hint,
&native_spec,
sys::imageio::OpenMode::Create,
)
.map_err(|message| Error::OpenImage {
path: PathBuf::from(name_hint),
message,
})?;
output.adopt_open_spec(spec);
Ok(output)
}
pub fn close_into_bytes(mut self) -> Result<Vec<u8>> {
if self.proxy.is_none() {
return Err(Error::operation(
"take encoded bytes",
"this writer targets a file, not memory".to_owned(),
));
}
let succeeded = sys::imageio::imageoutput_close(self.inner_mut());
self.check("close image", succeeded)?;
let proxy = self.proxy.as_ref().expect("checked above");
let proxy_ref = proxy.as_ref().ok_or_else(|| {
Error::operation(
"take encoded bytes",
"the memory proxy was released early".to_owned(),
)
})?;
Ok(sys::filesystem::ioproxy_vecoutput_bytes(proxy_ref))
}
pub fn plugin_supports(image_path: &Path, feature: &str) -> Result<bool> {
Ok(Self::open_plugin(image_path)?.supports(feature))
}
pub fn format_name(&self) -> &str {
sys::imageio::imageoutput_format_name(self.inner())
}
pub fn supports(&self, feature: &str) -> bool {
sys::imageio::imageoutput_supports(self.inner(), feature) != 0
}
pub fn spec(&self) -> &ImageSpec {
&self.spec
}
pub fn write_image<T: Pixel>(&mut self, pixels: &[T]) -> Result<()> {
self.reject_deep()?;
let expected = self.spec.element_count()?;
validate_buffer_len(expected, pixels.len())?;
let succeeded = unsafe {
sys::imageio::imageoutput_write_image_span(
self.inner_mut(),
pixel::type_desc::<T>(),
pixel::as_bytes(pixels),
)
};
self.check("write image", succeeded)?;
self.mark_whole_subimage_written();
Ok(())
}
pub fn write_scanlines<T: Pixel>(&mut self, y: Range<i32>, pixels: &[T]) -> Result<()> {
self.reject_deep()?;
if !self.supports("random_access") && y.start != self.next_scanline {
return Err(Error::InvalidRegion {
axis: "y",
message: format!(
"this format writes scanlines in order: the next row is {}, not {}",
self.next_scanline, y.start
),
});
}
if self.spec.dimensions()[2] != 1 {
return Err(Error::InvalidImageSpec(
"scanline writes require a two-dimensional image".to_owned(),
));
}
let rows = self.validate_axis("y", &y, self.spec.origin()[1], self.spec.dimensions()[1])?;
let expected = element_count([self.spec.dimensions()[0], rows, self.spec.channel_count()])?;
validate_buffer_len(expected, pixels.len())?;
let succeeded = unsafe {
sys::imageio::imageoutput_write_scanlines_span(
self.inner_mut(),
y.start,
y.end,
pixel::type_desc::<T>(),
pixel::as_bytes(pixels),
)
};
self.check("write scanlines", succeeded)?;
self.next_scanline = y.end;
Ok(())
}
pub fn write_tiles<T: Pixel>(
&mut self,
x: Range<i32>,
y: Range<i32>,
z: Range<i32>,
pixels: &[T],
) -> Result<()> {
self.reject_deep()?;
let [tile_width, tile_height, tile_depth] = self.spec.tile_dimensions();
if !self.spec.is_tiled() {
return Err(Error::InvalidImageSpec(
"tile writes require a specification with a tile size".to_owned(),
));
}
let origin = self.spec.origin();
let dimensions = self.spec.dimensions();
let width = self.validate_axis("x", &x, origin[0], dimensions[0])?;
let height = self.validate_axis("y", &y, origin[1], dimensions[1])?;
let depth = self.validate_axis("z", &z, origin[2], dimensions[2])?;
validate_tile_alignment("x", &x, origin[0], dimensions[0], tile_width)?;
validate_tile_alignment("y", &y, origin[1], dimensions[1], tile_height)?;
validate_tile_alignment("z", &z, origin[2], dimensions[2], tile_depth.max(1))?;
let expected = element_count([width, height, depth, self.spec.channel_count()])?;
validate_buffer_len(expected, pixels.len())?;
let succeeded = unsafe {
sys::imageio::imageoutput_write_tiles_span(
self.inner_mut(),
x.start,
x.end,
y.start,
y.end,
z.start,
z.end,
pixel::type_desc::<T>(),
pixel::as_bytes(pixels),
)
};
self.check("write tiles", succeeded)?;
self.mark_whole_subimage_written();
Ok(())
}
pub fn write_deep_image(&mut self, deep: &DeepImage) -> Result<()> {
if !self.spec.is_deep() {
return Err(Error::operation(
"write deep image",
"this writer was opened for flat pixels; see ImageSpec::as_deep".to_owned(),
));
}
let dimensions = self.spec.dimensions();
if deep.dimensions() != dimensions {
return Err(Error::InvalidImageSpec(format!(
"the deep image is {:?} but the writer expects {dimensions:?}",
deep.dimensions()
)));
}
if deep.channel_count() != self.spec.channel_count() {
return Err(Error::InvalidImageSpec(format!(
"the deep image has {} channels but the writer expects {}",
deep.channel_count(),
self.spec.channel_count()
)));
}
let succeeded = sys::imageio::imageoutput_write_deep_image(self.inner_mut(), deep.native());
self.check("write deep image", succeeded)?;
self.mark_whole_subimage_written();
Ok(())
}
pub fn write_deep_scanlines(&mut self, y: Range<i32>, deep: &DeepImage) -> Result<()> {
const OPERATION: &str = "write deep scanlines";
self.require_deep_writer(OPERATION)?;
if self.spec.is_tiled() {
return Err(Error::InvalidImageSpec(
"this file is tiled; use write_deep_tiles".to_owned(),
));
}
if self.spec.dimensions()[2] != 1 {
return Err(Error::InvalidImageSpec(
"scanline writes require a two-dimensional image".to_owned(),
));
}
if !self.supports("random_access") && y.start != self.next_scanline {
return Err(Error::InvalidRegion {
axis: "y",
message: format!(
"this format writes scanlines in order: the next row is {}, not {}",
self.next_scanline, y.start
),
});
}
let rows = validate_axis("y", &y, self.spec.origin()[1], self.spec.dimensions()[1])?;
self.require_deep_band(OPERATION, deep, [self.spec.dimensions()[0], rows, 1])?;
let succeeded = sys::imageio::imageoutput_write_deep_scanlines(
self.inner_mut(),
y.start,
y.end,
0,
deep.native(),
);
self.check(OPERATION, succeeded)?;
self.next_scanline = y.end;
Ok(())
}
pub fn write_deep_tiles(
&mut self,
x: Range<i32>,
y: Range<i32>,
z: Range<i32>,
deep: &DeepImage,
) -> Result<()> {
const OPERATION: &str = "write deep tiles";
self.require_deep_writer(OPERATION)?;
let [tile_width, tile_height, tile_depth] = self.spec.tile_dimensions();
if !self.spec.is_tiled() {
return Err(Error::InvalidImageSpec(
"tile writes require a specification with a tile size".to_owned(),
));
}
let origin = self.spec.origin();
let dimensions = self.spec.dimensions();
let width = validate_axis("x", &x, origin[0], dimensions[0])?;
let height = validate_axis("y", &y, origin[1], dimensions[1])?;
let depth = validate_axis("z", &z, origin[2], dimensions[2])?;
validate_tile_alignment("x", &x, origin[0], dimensions[0], tile_width)?;
validate_tile_alignment("y", &y, origin[1], dimensions[1], tile_height)?;
validate_tile_alignment("z", &z, origin[2], dimensions[2], tile_depth.max(1))?;
self.require_deep_band(OPERATION, deep, [width, height, depth])?;
let succeeded = sys::imageio::imageoutput_write_deep_tiles(
self.inner_mut(),
x.start,
x.end,
y.start,
y.end,
z.start,
z.end,
deep.native(),
);
self.check(OPERATION, succeeded)?;
self.mark_whole_subimage_written();
Ok(())
}
fn require_deep_writer(&self, operation: &'static str) -> Result<()> {
if !self.spec.is_deep() {
return Err(Error::operation(
operation,
"this writer was opened for flat pixels; see ImageSpec::as_deep".to_owned(),
));
}
if !self.supports("deepdata") {
return Err(Error::operation(
operation,
format!(
"the {} format does not support deep images",
self.format_name()
),
));
}
Ok(())
}
fn require_deep_band(
&self,
operation: &'static str,
deep: &DeepImage,
expected: [u32; 3],
) -> Result<()> {
if deep.dimensions() != expected {
return Err(Error::operation(
operation,
format!(
"the deep image is {:?} but the region covers {expected:?}",
deep.dimensions()
),
));
}
if deep.channel_count() != self.spec.channel_count() {
return Err(Error::operation(
operation,
format!(
"the deep image has {} channels but the writer expects {}",
deep.channel_count(),
self.spec.channel_count()
),
));
}
Ok(())
}
pub fn set_thumbnail(&mut self, thumbnail: &crate::ImageBuf) -> Result<()> {
const OPERATION: &str = "set thumbnail";
if !self.supports("thumbnail") {
return Err(Error::operation(
OPERATION,
format!(
"the {} format does not store thumbnails",
self.format_name()
),
));
}
if !self.supports("thumbnail_after_write") && self.next_scanline != self.spec.origin()[1] {
return Err(Error::operation(
OPERATION,
"this format needs the thumbnail before any pixels are written".to_owned(),
));
}
let thumb_spec = thumbnail.spec()?;
let [width, height, _] = thumb_spec.dimensions();
if width == 0 || height == 0 {
return Err(Error::operation(
OPERATION,
"the thumbnail has no pixels".to_owned(),
));
}
if width >= 256 || height >= 256 {
return Err(Error::operation(
OPERATION,
format!(
"a {width}×{height} thumbnail cannot be stored: dimensions must be \
under 256, and OpenImageIO's own downsizing clamps to 256 and \
truncates it to zero; resize it first"
),
));
}
if thumb_spec.channel_count() != self.spec.channel_count() {
return Err(Error::operation(
OPERATION,
format!(
"the thumbnail has {} channels but the image has {}",
thumb_spec.channel_count(),
self.spec.channel_count()
),
));
}
let succeeded =
sys::imageio::imageoutput_set_thumbnail(self.inner_mut(), thumbnail.inner());
self.check(OPERATION, succeeded)
}
pub fn append_subimage(&mut self, spec: &ImageSpec) -> Result<()> {
self.append(
spec,
sys::imageio::OpenMode::AppendSubimage,
"append subimage",
)
}
pub fn append_mip_level(&mut self, spec: &ImageSpec) -> Result<()> {
self.append(
spec,
sys::imageio::OpenMode::AppendMIPLevel,
"append mip level",
)
}
pub fn threads(&self) -> i32 {
sys::imageio::imageoutput_threads(self.inner())
}
pub fn set_threads(&mut self, threads: i32) {
sys::imageio::imageoutput_set_threads(self.inner_mut(), threads);
}
pub fn close(mut self) -> Result<()> {
let succeeded = sys::imageio::imageoutput_close(self.inner_mut());
self.check("close image", succeeded)
}
fn open_plugin(image_path: &Path) -> Result<Self> {
let image_path_str = path_to_utf8(image_path)?;
let inner =
unsafe { sys::imageio::imageoutput_create(image_path_str, std::ptr::null_mut(), "") };
if inner.is_null() {
return Err(Error::CreateImage {
path: image_path.to_path_buf(),
message: global_error(),
});
}
Ok(Self {
inner,
path: image_path.to_path_buf(),
spec: ImageSpec::new(1, 1, 1, crate::PixelFormat::U8)?,
next_scanline: 0,
proxy: None,
})
}
fn open_native(
output: std::pin::Pin<&mut sys::imageio::ImageOutput>,
path: &str,
spec: &cxx::UniquePtr<sys::imageio::ImageSpec>,
mode: sys::imageio::OpenMode,
) -> std::result::Result<(), String> {
let Some(native_spec) = spec.as_ref() else {
return Err("OpenImageIO could not allocate an image specification".to_owned());
};
if sys::imageio::imageoutput_open(output, path, native_spec, mode) {
Ok(())
} else {
Err(String::new())
}
}
fn append(
&mut self,
spec: &ImageSpec,
mode: sys::imageio::OpenMode,
operation: &'static str,
) -> Result<()> {
let native_spec = spec.to_sys()?;
let path = path_to_utf8(&self.path)?.to_owned();
let opened = Self::open_native(self.inner_mut(), &path, &native_spec, mode);
match opened {
Ok(()) => {
self.adopt_open_spec(spec);
Ok(())
}
Err(message) if message.is_empty() => Err(self.take_error(operation)),
Err(message) => Err(Error::operation(operation, message)),
}
}
fn validate_axis(
&self,
axis: &'static str,
range: &Range<i32>,
origin: i32,
size: u32,
) -> Result<u32> {
validate_axis(axis, range, origin, size)
}
}
fn validate_axis(axis: &'static str, range: &Range<i32>, origin: i32, size: u32) -> Result<u32> {
if range.start >= range.end {
return Err(Error::InvalidRegion {
axis,
message: format!(
"range must be non-empty and increasing, got {}..{}",
range.start, range.end
),
});
}
let end = i64::from(origin) + i64::from(size);
if i64::from(range.start) < i64::from(origin) || i64::from(range.end) > end {
return Err(Error::InvalidRegion {
axis,
message: format!(
"range {}..{} lies outside the data window {origin}..{end}",
range.start, range.end
),
});
}
Ok((i64::from(range.end) - i64::from(range.start)) as u32)
}
impl ImageOutput {
fn reject_deep(&self) -> Result<()> {
if self.spec.is_deep() {
return Err(Error::UnsupportedDeepImage);
}
Ok(())
}
fn check(&mut self, operation: &'static str, succeeded: bool) -> Result<()> {
if succeeded {
Ok(())
} else {
Err(self.take_error(operation))
}
}
fn inner(&self) -> &sys::imageio::ImageOutput {
self.inner
.as_ref()
.expect("ImageOutput invariant violated: null native pointer")
}
fn inner_mut(&mut self) -> std::pin::Pin<&mut sys::imageio::ImageOutput> {
self.inner
.as_mut()
.expect("ImageOutput invariant violated: null native pointer")
}
pub(crate) fn native_mut(&mut self) -> std::pin::Pin<&mut sys::imageio::ImageOutput> {
self.inner_mut()
}
pub(crate) fn scanline_cursor(&self) -> i32 {
self.next_scanline
}
pub(crate) fn mark_whole_subimage_written(&mut self) {
let end = i64::from(self.spec.origin()[1]) + i64::from(self.spec.dimensions()[1]);
self.next_scanline = end.min(i64::from(i32::MAX)) as i32;
}
pub fn write_rectangle<T: Pixel>(
&mut self,
x: Range<i32>,
y: Range<i32>,
pixels: &[T],
) -> Result<()> {
self.reject_deep()?;
if !self.supports("rectangles") {
return Err(Error::operation(
"write rectangle",
format!(
"the {} format cannot place arbitrary rectangles; OpenImageIO's \
fallback fails without a message, so it is refused here",
self.format_name()
),
));
}
let origin = self.spec.origin();
let dimensions = self.spec.dimensions();
let width = self.validate_axis("x", &x, origin[0], dimensions[0])?;
let height = self.validate_axis("y", &y, origin[1], dimensions[1])?;
let expected = element_count([width, height, 1, self.spec.channel_count()])?;
validate_buffer_len(expected, pixels.len())?;
let succeeded = unsafe {
sys::imageio::imageoutput_write_rectangle_span(
self.inner_mut(),
x.start,
x.end,
y.start,
y.end,
0,
1,
pixel::type_desc::<T>(),
pixel::as_bytes(pixels),
)
};
self.check("write rectangle", succeeded)?;
self.mark_whole_subimage_written();
Ok(())
}
pub fn copy_image_from(&mut self, input: &mut ImageInput) -> Result<()> {
const OPERATION: &str = "copy image from reader";
let top = self.spec.origin()[1];
if self.next_scanline != top {
return Err(Error::operation(
OPERATION,
format!(
"rows {top}..{} of this subimage were already written; the copy \
needs an untouched subimage",
self.next_scanline
),
));
}
let succeeded = unsafe {
let in_ptr = input.native_mut().get_unchecked_mut() as *mut sys::imageio::ImageInput;
sys::imageio::imageoutput_copy_image(self.inner_mut(), in_ptr)
};
if !succeeded {
return Err(self.take_error(OPERATION));
}
self.mark_whole_subimage_written();
Ok(())
}
fn take_error(&mut self, operation: &'static str) -> Error {
Error::operation(
operation,
sys::imageio::imageoutput_geterror(self.inner(), true),
)
}
}
fn validate_tile_alignment(
axis: &'static str,
range: &Range<i32>,
origin: i32,
size: u32,
tile: u32,
) -> Result<()> {
if tile == 0 {
return Err(Error::InvalidImageSpec(format!(
"tile size on the {axis} axis must be non-zero"
)));
}
let tile = i64::from(tile);
let edge = i64::from(origin) + i64::from(size);
if (i64::from(range.start) - i64::from(origin)) % tile != 0 {
return Err(Error::InvalidRegion {
axis,
message: format!("start {} is not on the {tile}-pixel tile grid", range.start),
});
}
if i64::from(range.end) != edge && (i64::from(range.end) - i64::from(origin)) % tile != 0 {
return Err(Error::InvalidRegion {
axis,
message: format!(
"end {} is neither on the {tile}-pixel tile grid nor at the data window edge {edge}",
range.end
),
});
}
Ok(())
}
fn global_error() -> String {
if sys::imageio::has_error() {
sys::imageio::get_error(true)
} else {
"OpenImageIO did not provide an error message".to_owned()
}
}
impl std::fmt::Debug for ImageInput {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter
.debug_struct("ImageInput")
.field("format", &self.format_name())
.finish_non_exhaustive()
}
}
impl std::fmt::Debug for ImageOutput {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter
.debug_struct("ImageOutput")
.field("path", &self.path)
.field("format", &self.format_name())
.field("dimensions", &self.spec.dimensions())
.field("pixel_format", &self.spec.format())
.finish_non_exhaustive()
}
}
fn level_index(index: u32) -> Result<i32> {
i32::try_from(index)
.map_err(|_| Error::InvalidImageSpec("image level index exceeds i32::MAX".to_owned()))
}
pub(crate) fn validate_buffer_len(expected: usize, actual: usize) -> Result<()> {
if expected == actual {
Ok(())
} else {
Err(Error::BufferLength { expected, actual })
}
}