Abstract writable view of one image file. More...

#include <vitrio/image_writer.hpp>

Public Member Functions
	image_writer (const image_writer &other)=delete

	image_writer (image_writer &&other)=delete

image_writer &	operator= (const image_writer &other)=delete

image_writer &	operator= (image_writer &&other)=delete

virtual const image_descriptor &	get_descriptor () const noexcept=0
	Get the shape and data type of the file.

virtual void	write (const_array_ref source, const image_transfer_plan &regions)=0
	Write a set of hyperrectangles of the file from one array.

virtual void	flush ()=0
	Make everything written so far reach the storage.

Detailed Description

Abstract writable view of one image file.

The mirror of image_reader, with the same regions, described by the same image_transfer_plan, the same conversion rule and the opposite direction. A writer is opened over complete extents, so the shape of the file is settled before anything is written; the file can be laid out once up front and a region can be written wherever it belongs, in any order.

Member Function Documentation

◆ flush()

virtual void vitrio::image_writer::flush ( )

pure virtual

Make everything written so far reach the storage.

Call this before dropping a writer whose failures matter. A writer flushes itself when it is destroyed, but a destructor can not report a failure, so a write that only fails on the way out is lost unless it was flushed explicitly.

Exceptions

image_file_error If the pending writes could not be completed.

◆ get_descriptor()

virtual const image_descriptor & vitrio::image_writer::get_descriptor ( ) const

pure virtualnoexcept

Get the shape and data type of the file.

The ones the writer was created over. The extents bound every region that may be written, and a write converts to the data type from whatever it is given. How the file lays its elements out within the extents is the format's own business and is not reported.

Returns: const image_descriptor& The descriptor. It refers to storage owned by this writer.

◆ write()

virtual void vitrio::image_writer::write	(	const_array_ref	source,
		const image_transfer_plan &	regions
	)

pure virtual

Write a set of hyperrectangles of the file from one array.

The mirror of image_reader::read, sharing its plan and naming its sides the same way: the file is the file side and source the array side, so every region names where it is taken from in source and where it lands in the file, and all of them share the extents the plan carries. The plan is therefore built the same way for a write as for a read. Passing every region in one call lets a writer order and merge the accesses it is about to make, and pays for the source's geometry once.

source is the whole array and may be strided. Its rank must be the array rank of the plan and the file's the file rank, and values are converted as a cast between the two types does, without scaling or normalising.

Regions that do not overlap may be written by concurrent calls. Overlapping ones may not, and where two regions of one call land on the same elements of the file, which one prevails is unspecified.

A region that is never written keeps whatever the format leaves in a file it has laid out but not filled. An empty plan writes nothing and succeeds.

Parameters

source	The values to write. Must be initialized.
regions	The regions to write and where each one comes from.