Skip to main content

ImageOutput

Struct ImageOutput 

Source
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

Source

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.

Source

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.

Source

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.

Source

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.

Source

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".

Source

pub fn format_name(&self) -> &str

Return the output plugin’s format name.

Source

pub fn supports(&self, feature: &str) -> bool

Whether the open plugin supports a named feature.

Source

pub fn spec(&self) -> &ImageSpec

The specification the file is currently open with.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn threads(&self) -> i32

Get the current thread count.

Source

pub fn set_threads(&mut self, threads: i32)

Set the thread count. Zero requests OpenImageIO’s default.

Source

pub fn close(self) -> Result<()>

Finish the file and report any delayed format or I/O errors.

Dropping an ImageOutput without calling this method still closes the file, but cannot report errors that only surface at close time.

Source§

impl ImageOutput

Source

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.

Source

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.

Trait Implementations§

Source§

impl Debug for ImageOutput

Source§

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Send for ImageOutput

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.