MPSImageHistogramEqualization
#import <MPSImageHistogram.h>
Inherits MPSUnaryImageKernel.
(nonnull instancetype) - initWithDevice:histogramInfo:
(nullable instancetype) - initWithCoder:device:
(void) -
encodeTransformToCommandBuffer:sourceTexture:histogram:histogramOffset:
MPSImageHistogramInfo histogramInfo
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.
- (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.
- (nullable instancetype) initWithCoder: (NSCoder
*__nonnull) aDecoder(nonnull id< MTLDevice >) device
NSSecureCoding compatability While the standard
NSSecureCoding/NSCoding method -initWithCoder: should work, since the file
can't know which device your data is allocated on, we have to guess and may
guess incorrectly. To avoid that problem, use initWithCoder:device
instead.
Parameters:
aDecoder The NSCoder subclass with your serialized
MPSKernel
device The MTLDevice on which to make the MPSKernel
Returns:
A new MPSKernel object, or nil if
failure.
Reimplemented from MPSUnaryImageKernel.
- (nonnull instancetype) initWithDevice: (nonnull id<
MTLDevice >) device(const MPSImageHistogramInfo *__nonnull)
histogramInfo
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.
- histogramInfo [read], [nonatomic], [assign]
Return a structure describing the histogram content Returns a
MPSImageHistogramInfo structure describing the format of the
histogram.
Generated automatically by Doxygen for
MetalPerformanceShaders.framework from the source code.