<commit_before>\chapter{Image Buffers}
\label{chap:imagebuf}
\index{Image Buffers|(}
\index{ImageBuf|(}

\section{ImageBuf Introduction and Theory of Operation}
\label{sec:imagebuf:intro}

\ImageBuf is a utility class that stores an entire image.  It provides a
nice API for reading, writing, and manipulating images as a single unit,
without needing to worry about any of the details of storage or I/O.

\smallskip

\noindent An \ImageBuf can store its pixels in one of several ways:

\begin{itemize}
\item Allocate ``local storage'' to hold the image pixels
internal to the \ImageBuf.  This storage will be freed when the
\ImageBuf is destroyed.
\item ``Wrap'' pixel memory already allocated by the calling application,
which will continue to own that memory and be responsible for freeing
it after the \ImageBuf is destroyed.
\item Be ``backed'' by an \ImageCache, which will automatically be used
to retreive pixels when requested, but the \ImageBuf will not allocate
separate storage for it.  This brings all the advantages of the
\ImageCache, but can only be used for read-only \ImageBuf's that
reference a stored image file.
\end{itemize}

All I/O involving \ImageBuf (that is, calls to {\cf read} or {\cf write})
are implemented in terms of \ImageCache, \ImageInput,
and \ImageOutput underneath, and so support all of the image file
formats supported by OIIO.

\smallskip

\noindent The \ImageBuf class definition requires that you
\begin{code}
  #include <OpenImageIO/imagebuf.h>
\end{code}




\section{Constructing, reading, and writing an \ImageBuf}

\subsection*{Default constructor of an empty \ImageBuf}

\apiitem{{\ce ImageBuf} ()}
The default constructor makes an uninitialized \ImageBuf.  There isn't
much you can do with an uninitialized buffer until you call {\cf reset()}.
\apiend

\apiitem{void {\ce clear} ()}
Resets the \ImageBuf to a pristine state identical to that of a freshly
constructed \ImageBuf using the default constructor.
\apiend


\subsection*{Constructing and initializing a writeable \ImageBuf}

\apiitem{{\ce ImageBuf} (const ImageSpec \&spec, \\
\big\big InitializePixels zero = InitializePixels::Yes) \\
{\ce ImageBuf} (string_view name, const ImageSpec \&spec,
\big\big InitializePixels zero = InitializePixels::Yes)}
Constructs a writeable \ImageBuf with the given specification (including
resolution, data type, metadata, etc.).
The {\cf zero} parameter controls whether the pixel values are filled with
black/empty, or are left uninitialized after being allocated (if set to
{\cf InitializePixels::No}).
Optionally, you may name the \ImageBuf.
\apiend

\apiitem{void {\ce reset} (const ImageSpec \&spec, bool zero = true) \\
void {\ce reset} (string_view name, const ImageSpec \&spec, bool zero = true)}
Destroys any previous contents of the \ImageBuf and re-initializes it
as a writeable all-black \ImageBuf with the given specification (including<commit_msg>Fix docs typos<commit_after>\chapter{Image Buffers}
\label{chap:imagebuf}
\index{Image Buffers|(}
\index{ImageBuf|(}

\section{ImageBuf Introduction and Theory of Operation}
\label{sec:imagebuf:intro}

\ImageBuf is a utility class that stores an entire image.  It provides a
nice API for reading, writing, and manipulating images as a single unit,
without needing to worry about any of the details of storage or I/O.

\smallskip

\noindent An \ImageBuf can store its pixels in one of several ways:

\begin{itemize}
\item Allocate ``local storage'' to hold the image pixels
internal to the \ImageBuf.  This storage will be freed when the
\ImageBuf is destroyed.
\item ``Wrap'' pixel memory already allocated by the calling application,
which will continue to own that memory and be responsible for freeing
it after the \ImageBuf is destroyed.
\item Be ``backed'' by an \ImageCache, which will automatically be used
to retreive pixels when requested, but the \ImageBuf will not allocate
separate storage for it.  This brings all the advantages of the
\ImageCache, but can only be used for read-only \ImageBuf's that
reference a stored image file.
\end{itemize}

All I/O involving \ImageBuf (that is, calls to {\cf read} or {\cf write})
are implemented in terms of \ImageCache, \ImageInput,
and \ImageOutput underneath, and so support all of the image file
formats supported by OIIO.

\smallskip

\noindent The \ImageBuf class definition requires that you
\begin{code}
  #include <OpenImageIO/imagebuf.h>
\end{code}




\section{Constructing, reading, and writing an \ImageBuf}

\subsection*{Default constructor of an empty \ImageBuf}

\apiitem{{\ce ImageBuf} ()}
The default constructor makes an uninitialized \ImageBuf.  There isn't
much you can do with an uninitialized buffer until you call {\cf reset()}.
\apiend

\apiitem{void {\ce clear} ()}
Resets the \ImageBuf to a pristine state identical to that of a freshly
constructed \ImageBuf using the default constructor.
\apiend


\subsection*{Constructing and initializing a writeable \ImageBuf}

\apiitem{{\ce ImageBuf} (const ImageSpec \&spec, \\
\bigspc\bigspc InitializePixels zero = InitializePixels::Yes) \\
{\ce ImageBuf} (string_view name, const ImageSpec \&spec, \\
\bigspc\bigspc InitializePixels zero = InitializePixels::Yes) }
Constructs a writeable \ImageBuf with the given specification (including
resolution, data type, metadata, etc.).
The {\cf zero} parameter controls whether the pixel values are filled with
black/empty, or are left uninitialized after being allocated (if set to
{\cf InitializePixels::No}).
Optionally, you may name the \ImageBuf.
\apiend

\apiitem{void {\ce reset} (const ImageSpec \&spec, bool zero = true) \\
void {\ce reset} (string_view name, const ImageSpec \&spec, bool zero = true)}
Destroys any previous contents of the \ImageBuf and re-initializes it
as a writeable all-black \ImageBuf with the given specification (including
{'fraction_non_alphanumeric': 0.08406244638874592, 'fraction_numerical': 0.0, 'mean_word_length': 4.600384245917387, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4079521', 'n_tokens_mistral': 1635, 'n_tokens_neox': 1617, 'n_words': 771}