Create a new heap structure
#include "dip_pixelqueue.h"
dip_Error dip_PixelHeapNew ( heap, ndims, blocksize, order, resources )
This function allocates space for a new dip_PixelHeap structure. Memory allocated is tracked in resources. The heap is dimensioned to hold pixels from an ndims-dimensional image, and initially enough space is allocated for blocksize elements. The heap will be expanded as necessary when used.
The heap stores the coordinates, the value and the pointer to a pixel in an image. Note that the value does not need to equal the data pointed to by the pointer. ndims can be set to zero, in which case no coordinates are stored; this does not affect the function of the value and the pointer.
A heap is a priority queue data structure. Just like a queue, items can be added (pushed) and subtracted (popped). However, in the priority queue the item popped is always the higherst priority one: either the one with the highest-valued item (order is DIP_GVSO_HIGH_FIRST) or lowest-valued item (order is DIP_GVSO_LOW_FIRST). However, identically-valued items are stored on the heap in unpredictable order. If this order is important (such as for the GrowRegions algorithm with integer-valued pixels, use a dip_StablePixelHeap instead. See StablePixelHeapNew for information on the stable heap structure.
| Data type | Name | Description |
| dip_PixelHeap * | heap | The newly allocated heap structure |
| dip_int | ndims | Image dimensionality |
| dip_int | blocksize | Size of each allocation block |
| dipf_GreyValueSortOrder | order | Determines the heap's sort order |
| dip_Resources | resources | Resources tracking structure. See ResourcesNew |
The dipf_GreyValueSortOrder enumeration consists of the following values:
| Name | Description |
| DIP_GVSO_HIGH_FIRST | Process the pixels from high grey-value to low grey-value. |
| DIP_GVSO_LOW_FIRST | Process the pixels from low grey-value to high grey-value. |
When the heap grows beyond its initial size, its capacity is doubled in size by reallocating the data blocks. However, when removing pixels from the queue, the heap is not shrunk. It is assumed that the dip_PixelHeap structure will be destroyed as soon as the algorithm using it terminates. Reducing the memory footprint of the heap therefore has no benefit.
StablePixelHeapNew, PixelQueueNew, PixelHeapFree, PixelHeapPush, PixelHeapPop, PixelHeapIsEmpty