MPSImageHistogramEqualization(3) MetalPerformanceShaders.framework MPSImageHistogramEqualization(3)
NAME
MPSImageHistogramEqualization
SYNOPSIS
#import <MPSImageHistogram.h>
Inherits MPSUnaryImageKernel.
Instance Methods
(nonnull instancetype) - initWithDevice:histogramInfo:
(nullable instancetype) - initWithCoder:device:
(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.
- (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.
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.
Version MetalPerformanceShaders-100 Thu Feb 8 2018 MPSImageHistogramEqualization(3)