Modules | Alphabetical List | Class List | Directories | File List | GIL Home Page

# STL-like Algorithms
[Algorithms and Utility Functions]

## Detailed Description

Image view-equivalents of STL algorithms.

Image views provide 1D iteration of their pixels via `begin()` and `end()` methods, which makes it possible to use STL algorithms with them. However, using nested loops over X and Y is in many cases more efficient. The algorithms in this section resemble STL algorithms, but they abstract away the nested loops and take views (as opposed to ranges) as input.

Most algorithms check whether the image views are 1D-traversable. A 1D-traversable image view has no gaps at the end of the rows. In other words, if an x_iterator of that view is advanced past the last pixel in a row it will move to the first pixel of the next row. When image views are 1D-traversable, the algorithms use a single loop and run more efficiently. If one or more of the input views are not 1D-traversable, the algorithms fall-back to an X-loop nested inside a Y-loop.

The algorithms typically delegate the work to their corresponding STL algorithms. For example, `copy_pixels` calls `std::copy` either for each row, or, when the images are 1D-traversable, once for all pixels.

In addition, overloads are sometimes provided for the STL algorithms. For example, std::copy for planar iterators is overloaded to perform `std::copy` for each of the planes. `std::copy` over bitwise-copiable pixels results in std::copy over unsigned char, which STL typically implements via `memmove`.

As a result `copy_pixels` may result in a single call to `memmove` for interleaved 1D-traversable views, or one per each plane of planar 1D-traversable views, or one per each row of interleaved non-1D-traversable images, etc.

## Modules

| copy_pixels
| std::copy for image views

| copy_and_convert_pixels
| copies src view into dst view, color converting if necessary.

| fill_pixels
| std::fill for image views

| destruct_pixels
| invokes the destructor on every pixel of an image view

| uninitialized_fill_pixels
| std::uninitialized_fill for image views

| default_construct_pixels
| invokes the default constructor on every pixel of an image view

| uninitialized_copy_pixels
| std::uninitialized_copy for image views

| for_each_pixel
| std::for_each for image views

| for_each_pixel_position
| adobe::for_each_position for image views (passes locators, instead of pixel references, to the function object)

| generate_pixels
| std::generate for image views

| equal_pixels
| std::equal for image views

| transform_pixels
| std::transform for image views

| transform_pixel_positions
| adobe::transform_positions for image views (passes locators, instead of pixel references, to the function object)

## Classes

struct | binary_operation_obj

A generic binary operation on views

Use this class as a convenience superclass when defining an operation for any image views. Many operations have different behavior when the two views are compatible. This class checks for compatibility and invokes apply_compatible(V1,V2) or apply_incompatible(V1,V2) of the subclass. You must provide apply_compatible(V1,V2) method in your subclass, but apply_incompatible(V1,V2) is not required and the default throws std::bad_cast. More...