pub struct ImageOutput { /* private fields */ }Expand description
An image file open for writing.
A writer is always open: ImageOutput::create selects the plugin from
the file name and opens the file in one step, so there is no state in which
a write can be attempted against an unopened file.
use oiio::{f16, ImageOutput, ImageSpec, PixelFormat};
use std::path::Path;
let spec = ImageSpec::new(64, 64, 3, PixelFormat::F16)?;
let pixels = vec![f16::ZERO; spec.element_count()?];
let mut output = ImageOutput::create(Path::new("out.exr"), &spec)?;
output.write_image(&pixels)?;
output.close()?;Implementations§
Source§impl ImageOutput
impl ImageOutput
Sourcepub fn create(image_path: &Path, spec: &ImageSpec) -> Result<Self>
pub fn create(image_path: &Path, spec: &ImageSpec) -> Result<Self>
Create and open an image file described by spec.
The output plugin is chosen from the file name’s extension. The file is truncated if it already exists.
Sourcepub fn create_multi_subimage(
image_path: &Path,
specs: &[ImageSpec],
) -> Result<Self>
pub fn create_multi_subimage( image_path: &Path, specs: &[ImageSpec], ) -> Result<Self>
Create and open a multi-part file, declaring every subimage up front.
Some formats — OpenEXR among them — must know all subimages when the
file is opened and reject ImageOutput::append_subimage. After this
call the writer is positioned on the first subimage; advance with
ImageOutput::append_subimage, passing the same specifications in
the same order.
Sourcepub fn to_memory(name_hint: &str, spec: &ImageSpec) -> Result<Self>
pub fn to_memory(name_hint: &str, spec: &ImageSpec) -> Result<Self>
Write an image into memory instead of a file.
name_hint is never created on disk; it only selects the writer, so
its extension decides the encoding. Finish with
ImageOutput::close_into_bytes to take the encoded bytes.
Not every format can write to memory — those that cannot are reported here rather than at close time.
Sourcepub fn close_into_bytes(self) -> Result<Vec<u8>>
pub fn close_into_bytes(self) -> Result<Vec<u8>>
Finish an in-memory write and take the encoded bytes.
Returns Error::Operation if this writer targets a file, since there
are no bytes to hand back; use ImageOutput::close for those.
Sourcepub fn plugin_supports(image_path: &Path, feature: &str) -> Result<bool>
pub fn plugin_supports(image_path: &Path, feature: &str) -> Result<bool>
Ask whether the output plugin for image_path supports a feature,
without creating the file.
Features are OpenImageIO’s own names, such as "tiles",
"mipmap", "multiimage", or "deepdata".
Sourcepub fn format_name(&self) -> &str
pub fn format_name(&self) -> &str
Return the output plugin’s format name.
Sourcepub fn supports(&self, feature: &str) -> bool
pub fn supports(&self, feature: &str) -> bool
Whether the open plugin supports a named feature.
Sourcepub fn write_image<T: Pixel>(&mut self, pixels: &[T]) -> Result<()>
pub fn write_image<T: Pixel>(&mut self, pixels: &[T]) -> Result<()>
Write every pixel of the current subimage and mip level.
The buffer length must exactly equal
width * height * depth * channels. Values are converted to the
specification’s pixel format by OpenImageIO.
Sourcepub fn write_scanlines<T: Pixel>(
&mut self,
y: Range<i32>,
pixels: &[T],
) -> Result<()>
pub fn write_scanlines<T: Pixel>( &mut self, y: Range<i32>, pixels: &[T], ) -> Result<()>
Write a contiguous range of scanlines of a two-dimensional image.
The buffer length must exactly equal
width * rows * channels, where rows is the length of y.
Unless the format reports the random_access feature, rows must be
written in order: the first call starts at the top of the data window
and each one continues where the last ended. This is not a limitation of
this crate but of the formats. OpenEXR’s scanline writer computes a
“virtual framebuffer” base by biasing the caller’s pointer backwards by
the requested row, then hands it to a writer that keeps its own cursor
starting at the top of the data window and only ever advancing. Ask it
to write rows 512..1024 first and it reads 512 scanlines before the
buffer. supports("random_access") is how OpenImageIO publishes the
difference. For EXR it is true only for tiled files with a random
line order; several formats that buffer the whole image before
writing — DPX, FITS, GIF, RLA and WebP among them — advertise it
unconditionally, and genuinely accept rows in any order.
Sourcepub fn write_tiles<T: Pixel>(
&mut self,
x: Range<i32>,
y: Range<i32>,
z: Range<i32>,
pixels: &[T],
) -> Result<()>
pub fn write_tiles<T: Pixel>( &mut self, x: Range<i32>, y: Range<i32>, z: Range<i32>, pixels: &[T], ) -> Result<()>
Write a rectangular block of whole tiles.
Each range must start on a tile boundary and either end on one or end at the edge of the data window. The buffer length must exactly equal the number of scalar values the block covers.
Sourcepub fn write_deep_image(&mut self, deep: &DeepImage) -> Result<()>
pub fn write_deep_image(&mut self, deep: &DeepImage) -> Result<()>
Write a deep image.
The writer must have been opened with a specification marked deep, and the image must match the size and channels it declared.
Sourcepub fn write_deep_scanlines(
&mut self,
y: Range<i32>,
deep: &DeepImage,
) -> Result<()>
pub fn write_deep_scanlines( &mut self, y: Range<i32>, deep: &DeepImage, ) -> Result<()>
Write a contiguous band of scanlines of a deep image.
The deep image must be exactly the band: as wide as the data window,
as tall as y, one channel per declared channel. Its own origin does
not matter — the samples land at y. Channel types that differ from
the declared ones are converted by OpenImageIO.
Bands must arrive in order, each starting where the previous ended: OpenEXR’s deep scanline writer keeps its own advancing cursor but trusts the caller’s starting row when it lays the sample arrays over the file, so an out-of-order band would be read outside its arrays.
Sourcepub fn write_deep_tiles(
&mut self,
x: Range<i32>,
y: Range<i32>,
z: Range<i32>,
deep: &DeepImage,
) -> Result<()>
pub fn write_deep_tiles( &mut self, x: Range<i32>, y: Range<i32>, z: Range<i32>, deep: &DeepImage, ) -> Result<()>
Write a rectangular block of whole tiles of a deep image.
Each range must start on a tile boundary and either end on one or end at the edge of the data window — OpenEXR positions the block by tile index, so a misaligned range would place samples at rows and columns the deep image does not hold. The deep image must be exactly the block: its size equal to the ranges, one channel per declared channel; its own origin does not matter.
Sourcepub fn set_thumbnail(&mut self, thumbnail: &ImageBuf) -> Result<()>
pub fn set_thumbnail(&mut self, thumbnail: &ImageBuf) -> Result<()>
Attach a thumbnail to the image being written.
Only formats reporting the thumbnail capability store one — among
real formats in OpenImageIO 3.1 that is Targa alone; the null
testing sink also claims it, then discards the call with
OpenImageIO’s messageless fallback — and that fallback fails without
recording anything, so formats not claiming the capability are
refused here with a clear message. The thumbnail’s channel count must match the
image’s (Targa refuses a mismatch silently), and both dimensions
must be under 256: the TGA postage stamp stores its size in single
bytes, and through 3.1.15 OpenImageIO’s own downsizing clamps to
256 — one past what the byte holds — silently writing a
zero-dimension thumbnail. (3.1.16 resizes to 255 itself; the refusal
here is version-independent.) Formats not reporting
thumbnail_after_write additionally need the thumbnail set before
any pixels.
Sourcepub fn append_subimage(&mut self, spec: &ImageSpec) -> Result<()>
pub fn append_subimage(&mut self, spec: &ImageSpec) -> Result<()>
Begin a new subimage in the same file.
Only supported by formats that report the "multiimage" feature.
Sourcepub fn append_mip_level(&mut self, spec: &ImageSpec) -> Result<()>
pub fn append_mip_level(&mut self, spec: &ImageSpec) -> Result<()>
Begin a new mip level of the current subimage.
Only supported by formats that report the "mipmap" feature.
Sourcepub fn set_threads(&mut self, threads: i32)
pub fn set_threads(&mut self, threads: i32)
Set the thread count. Zero requests OpenImageIO’s default.
Source§impl ImageOutput
impl ImageOutput
Sourcepub fn write_rectangle<T: Pixel>(
&mut self,
x: Range<i32>,
y: Range<i32>,
pixels: &[T],
) -> Result<()>
pub fn write_rectangle<T: Pixel>( &mut self, x: Range<i32>, y: Range<i32>, pixels: &[T], ) -> Result<()>
Write an arbitrary rectangle of pixels, for formats that can place pixels at random.
Only formats reporting the rectangles capability accept this —
ImageOutput::supports tells; OpenImageIO’s fallback for the rest
returns failure without recording a message, which this wrapper turns
into a clear error before calling. No format shipped with
OpenImageIO 3.1 reports the capability, so today this is refused for
every built-in writer; it exists for third-party plugins that do.
The rectangle must lie inside the data window and the buffer must
hold exactly its pixels. After a rectangle lands, the subimage
counts as written for the in-order scanline cursor.
Sourcepub fn copy_image_from(&mut self, input: &mut ImageInput) -> Result<()>
pub fn copy_image_from(&mut self, input: &mut ImageInput) -> Result<()>
Copy a reader’s current subimage into this writer — the lossless
transcode path iconvert is built on.
Pixel data is carried in the file’s native format wherever the formats allow, without a decode to a caller type in between; deep images are copied sample-for-sample. OpenImageIO verifies that the two specifications agree on dimensions and channel count and reports a clear error when they do not. Nothing may have been written to the current subimage yet, and the writer stays open afterwards.