fbec8a3aa4
Improve some titles and re-arrange several sections (e.g. in Metafunctions). Remove section about I/O extension from design guide as outdated and unnecessary (in design guide).
104 lines
3.5 KiB
ReStructuredText
104 lines
3.5 KiB
ReStructuredText
Image
|
|
=====
|
|
|
|
.. contents::
|
|
:local:
|
|
:depth: 2
|
|
|
|
Overview
|
|
--------
|
|
|
|
An image is a container that owns the pixels of a given image view
|
|
It allocates them in its constructor and deletes them in the destructor.
|
|
It has a deep assignment operator and copy constructor. Images are used
|
|
rarely, just when data ownership is important. Most STL algorithms operate on
|
|
ranges, not containers. Similarly most GIL algorithms operate on image views
|
|
(which images provide).
|
|
|
|
In the most general form images are N-dimensional and satisfy the following
|
|
concept:
|
|
|
|
.. code-block:: cpp
|
|
|
|
concept RandomAccessNDImageConcept<typename Img> : Regular<Img>
|
|
{
|
|
typename view_t; where MutableRandomAccessNDImageViewConcept<view_t>;
|
|
typename const_view_t = view_t::const_t;
|
|
typename point_t = view_t::point_t;
|
|
typename value_type = view_t::value_type;
|
|
typename allocator_type;
|
|
|
|
Img::Img(point_t dims, std::size_t alignment=0);
|
|
Img::Img(point_t dims, value_type fill_value, std::size_t alignment);
|
|
|
|
void Img::recreate(point_t new_dims, std::size_t alignment=0);
|
|
void Img::recreate(point_t new_dims, value_type fill_value, std::size_t alignment);
|
|
|
|
const point_t& Img::dimensions() const;
|
|
const const_view_t& const_view(const Img&);
|
|
const view_t& view(Img&);
|
|
};
|
|
|
|
Two-dimensional images have additional requirements:
|
|
|
|
.. code-block:: cpp
|
|
|
|
concept RandomAccess2DImageConcept<RandomAccessNDImageConcept Img>
|
|
{
|
|
typename x_coord_t = const_view_t::x_coord_t;
|
|
typename y_coord_t = const_view_t::y_coord_t;
|
|
|
|
Img::Img(x_coord_t width, y_coord_t height, std::size_t alignment=0);
|
|
Img::Img(x_coord_t width, y_coord_t height, value_type fill_value, std::size_t alignment);
|
|
|
|
x_coord_t Img::width() const;
|
|
y_coord_t Img::height() const;
|
|
|
|
void Img::recreate(x_coord_t width, y_coord_t height, std::size_t alignment=1);
|
|
void Img::recreate(x_coord_t width, y_coord_t height, value_type fill_value, std::size_t alignment);
|
|
};
|
|
|
|
GIL images have views that model ``ImageViewConcept`` and operate on pixels.
|
|
|
|
.. code-block:: cpp
|
|
|
|
concept ImageConcept<RandomAccess2DImageConcept Img>
|
|
{
|
|
where MutableImageViewConcept<view_t>;
|
|
typename coord_t = view_t::coord_t;
|
|
};
|
|
|
|
Images, unlike locators and image views, don't have 'mutable' set of concepts
|
|
because immutable images are not very useful.
|
|
|
|
.. seealso::
|
|
|
|
- `RandomAccessNDImageConcept<Image> <reference/structboost_1_1gil_1_1_random_access_n_d_image_concept.html>`_
|
|
- `RandomAccess2DImageConcept<Image> <reference/structboost_1_1gil_1_1_random_access2_d_image_concept.html>`_
|
|
- `ImageConcept<Image> <reference/structboost_1_1gil_1_1_image_concept.html>`_
|
|
|
|
Models
|
|
------
|
|
|
|
GIL provides a class, ``image``, which is templated over the value type
|
|
(the pixel) and models ``ImageConcept``:
|
|
|
|
.. code-block:: cpp
|
|
|
|
template
|
|
<
|
|
typename Pixel, // Models PixelValueConcept
|
|
bool IsPlanar, // planar or interleaved image
|
|
typename A=std::allocator<unsigned char>
|
|
>
|
|
class image;
|
|
|
|
The image constructor takes an alignment parameter which allows for
|
|
constructing images that are word-aligned or 8-byte aligned. The alignment is
|
|
specified in bytes. The default value for alignment is 0, which means there is
|
|
no padding at the end of rows. Many operations are faster using such
|
|
1D-traversable images, because ``image_view::x_iterator`` can be used to
|
|
traverse the pixels, instead of the more complicated ``image_view::iterator``.
|
|
Note that when alignment is 0, packed images are aligned to the bit - i.e.
|
|
there are no padding bits at the end of rows of packed images.
|