MPSImageHistogramEqualization(3)

NAME
MPSImageHistogramEqualization -

SYNOPSIS

#import <MPSImageHistogram.h>

Inherits MPSUnaryImageKernel.

  Instance Methods
(nonnull instancetype) - initWithDevice:histogramInfo:
(void) - encodeTransformToCommandBuffer:sourceTexture:histogram:histogramOffset:

  Properties
MPSImageHistogramInfo histogramInfo

  Additional Inherited Members

Detailed Description

The MPSImageHistogramEqualization performs equalizes the histogram of an image. The process is divided into three steps.

1.  Call -initWithDevice:histogramInfo: This creates a MPSImageHistogramEqualization object. It is done when the method returns.

2.  Call -encodeTransform:sourceTexture:histogram:histogramOffset: This creates a privately held image transform (i.e. a cumulative distribution function of the histogram) which will be used to equalize the distribution of the histogram of the source image. This process runs on a MTLCommandBuffer when it is committed to a MTLCommandQueue. It must complete before the next step can be run. It may be performed on the same MTLCommandBuffer. The histogram argument specifies the histogram buffer which contains the histogram values for sourceTexture. The sourceTexture argument is used by encodeTransform to determine the number of channels and therefore which histogram data in histogram buffer to use. The histogram for sourceTexture must have been computed either on the CPU or using the MPSImageHistogram kernel

3.  Call -encodeToCommandBuffer:sourceTexture:destinationTexture: to read data from sourceTexture, apply the equalization transform to it and write to destination texture. This step is also done on the GPU on a MTLCommandQueue.

You can reuse the same equalization transform on other images to perform the same transform on those images. (Since their distribution is probably different, they will probably not be equalized by it.) This filter usually will not be able to work in place.

Method Documentation

  - (void) encodeTransformToCommandBuffer: (nonnull id< MTLCommandBuffer >) commandBuffer(nonnull id< MTLTexture >) source(nonnull id< MTLBuffer >) histogram(NSUInteger) histogramOffset
Encode the transform function to a command buffer using a MTLComputeCommandEncoder. The transform function computes the equalization lookup table. The transform function will not begin to execute until after the command buffer has been enqueued and committed. This step will need to be repeated with the new MPSKernel if -copyWithZone:device or -copyWithZone: is called. The transform is stored as internal state to the object. You still need to call -encodeToCommandBuffer:sourceTexture:destinationTexture: afterward to apply the transform to produce a result texture.

Parameters:
    commandBuffer A valid MTLCommandBuffer.
    source A valid MTLTexture containing the source image for the filter.
    histogram A valid MTLBuffer containing the histogram results for an image. This filter will use these histogram results to generate the cumulative histogram for equalizing the image. The histogram results / channel are stored together. The number of channels for which histogram results are stored is determined by the number of channels in the image. If histogramInfo.histogramForAlpha is false and the source image is RGBA then only histogram results for RGB channels are stored.
    histogramOffset A byte offset into the histogram MTLBuffer where the histogram starts. Must conform to alignment requirements for [MTLComputeCommandEncoder setBuffer:offset:atIndex:] offset parameter.

  - (nonnull instancetype) initWithDevice: (nonnull id< MTLDevice >) device(const MPSImageHistogramInfo *__nonnull) NS_DESIGNATED_INITIALIZER
Specifies information about the histogram for the channels of an image.

Parameters:
    device The device the filter will run on
    histogramInfo Pointer to the MPSHistogramInfo struct

Returns:
    A valid MPSImageHistogramEqualization object or nil, if failure.

Property Documentation

  - histogramInfo [read], [nonatomic], [assign]
Return a structure describing the histogram content Returns a MPSImageHistogramInfo structure describing the format of the histogram.

Author

Generated automatically by Doxygen for MetalPerformanceShaders.framework from the source code.