public class MPSImage extends NSObject
A MPSImage object describes a MTLTexture that may have more than 4 channels.
Some image types, such as those found in convolutional neural networks (CNN) differ from a standard texture in that they may have more than 4 channels per image. While the channels could hold RGBA data, they will more commonly hold a number of structural permutations upon a multi-channel image as the neural network progresses. It is not uncommon for each pixel to have 32 or 64 channels in it.
A standard MTLTexture may have no more than 4 channels. The additional channels are stored in slices of 2d texture array (i.e. texture type is MTLTextureType2DArray) such that 4 consecutive channels are stored in each slice of this array. If the number of feature channels is N, number of array slices needed is (N+3)/4. E.g. a CNN image with width 3 and height 2 with 9 channels will be stored as [@code] slice 0 RGBA RGBA RGBA RGBA RGBA RGBA
slice 1 RGBA RGBA RGBA RGBA RGBA RGBA (ASCII art /diagonal offset/ intended to show a Z dimension)
slice 2 R??? R??? R??? R??? R??? R??? [@endcode] The width and height of underlying 2d texture array is the same as the width and height of the MPSImage. The array length is equal to (featureChannels + 3) / 4. Channels marked with ? are just for padding and should not contain NaNs or Infs.
A MPSImage can be container of multiple CNN images for batch processing. In order to create a MPSImage that contains N images, create MPSImageDescriptor with numberOfImages set to N.
Although a MPSImage can contain numberOfImages > 1, the actual number of images among these processed by MPSCNNKernel is controlled by z-dimension of the clipRect. A MPSCNNKernel processes n=clipRect.size.depth images from this collection. The starting source image index to process is given by offset.z. The starting index of the destination image is given by clipRect.origin.z. The MPSCNNKernel takes n=clipRect.size.depth images from tje source at indices [offset.z, offset.z+n], processes each independently and stores the result in the destination at indices [clipRect.origin.z, clipRect.origin.z+n] respectively. Offset.z+n should be <= [src numberOfImage] and clipRect.origin.z+n should be <= [dest numberOfImages] and offset.z must be >= 0.
Example: Suppose MPSCNNConvolution takes an input image with 8 channels and outputs an image with 16 channels. The number of slices needed in the source 2d texture array is 2 and the number of slices needed in the destination 2d array is 4. Suppose the source batch size is 5 and destination batch size is 4. (Multiple N-channel images can be processed concurrently in a batch.) The number of source slices will be 2*5=10 and number of destination slices will be 4*4=16. If you want to process just images 2 and 3 of the source and store the result at index 1 and 2 in the destination, you may achieve this by setting offset.z=2, clipRect.origin.z=1 and clipRect.size.depth=2. MPSCNNConvolution will take, in this case, slice 4 and 5 of source and produce slices 4 to 7 of destination. Similarly, slices 6 and 7 will be used to produce slices 8 to 11 of destination.
All MPSCNNKernels process images within each batch independently. That is, calling a MPSCNNKernel on an batch is formally the same as calling it on each image in the batch one at a time. However, quite a lot of CPU and GPU overhead will be avoided if batch processing is used. This is especially important for better performance on small images.
If the number of feature channels is <= 4 and numberOfImages = 1 i.e. only one slice is needed to represent a MPSImage, the underlying metal texture type will be MTLTextureType2D rather than MTLTextureType2DArray.
There are also MPSTemporaryImages, intended for use for very short-lived image data that are produced and consumed immediately in the same MTLCommandBuffer. They are a useful way to minimize CPU-side texture allocation costs and greatly reduce the amount of memory used by your image pipeline.
Creation of the underlying texture may in some cases occur lazily. You should in general avoid calling MPSImage.texture except when unavoidable to avoid materializing memory for longer than necessary. When possible, use the other MPSImage properties to get information about the MPSImage instead.
Most MPSImages of 4 or fewer feature channels can generate quicklooks output in Xcode for easy visualization of image data in the object. MPSTemporaryImages can not.
NSObject.Function_instanceMethodForSelector_ret, NSObject.Function_methodForSelector_ret| Modifier | Constructor and Description |
|---|---|
protected |
MPSImage(org.moe.natj.general.Pointer peer) |
| Modifier and Type | Method and Description |
|---|---|
static boolean |
accessInstanceVariablesDirectly() |
static MPSImage |
alloc() |
static MPSImage |
allocWithZone(org.moe.natj.general.ptr.VoidPtr zone) |
static boolean |
automaticallyNotifiesObserversForKey(java.lang.String key) |
static void |
cancelPreviousPerformRequestsWithTarget(java.lang.Object aTarget) |
static void |
cancelPreviousPerformRequestsWithTargetSelectorObject(java.lang.Object aTarget,
org.moe.natj.objc.SEL aSelector,
java.lang.Object anArgument) |
static NSArray<java.lang.String> |
classFallbacksForKeyedArchiver() |
static org.moe.natj.objc.Class |
classForKeyedUnarchiver() |
static java.lang.String |
debugDescription_static() |
static MPSImageAllocator |
defaultAllocator()
Get a well known MPSImageAllocator that makes MPSImages
|
static java.lang.String |
description_static() |
MTLDevice |
device()
[@property] device
|
long |
featureChannelFormat()
[@property] featureChannelFormat
|
long |
featureChannels()
[@property] featureChannels
|
static long |
hash_static() |
long |
height()
[@property] height
|
MPSImage |
init() |
MPSImage |
initWithDeviceImageDescriptor(MTLDevice device,
MPSImageDescriptor imageDescriptor)
Initialize an empty image object
|
MPSImage |
initWithParentImageSliceRangeFeatureChannels(MPSImage parent,
NSRange sliceRange,
long featureChannels)
Use -batchRepresentation or -subImageWithFeatureChannelRange instead
|
MPSImage |
initWithTextureFeatureChannels(MTLTexture texture,
long featureChannels)
Initialize an MPSImage object using Metal texture.
|
static NSObject.Function_instanceMethodForSelector_ret |
instanceMethodForSelector(org.moe.natj.objc.SEL aSelector) |
static NSMethodSignature |
instanceMethodSignatureForSelector(org.moe.natj.objc.SEL aSelector) |
static boolean |
instancesRespondToSelector(org.moe.natj.objc.SEL aSelector) |
static boolean |
isSubclassOfClass(org.moe.natj.objc.Class aClass) |
static NSSet<java.lang.String> |
keyPathsForValuesAffectingValueForKey(java.lang.String key) |
java.lang.String |
label()
[@property] label
|
static MPSImage |
new_objc() |
long |
numberOfImages()
[@property] numberOfImages
|
MPSImage |
parent()
The MPSImage from which this MPSImage was derived.
|
long |
pixelFormat()
[@property] pixelFormat
|
long |
pixelSize()
[@property] pixelSize
|
long |
precision()
[@property] precision
|
void |
readBytesDataLayoutBytesPerRowBytesPerImageRegionFeatureChannelInfoImageIndex(org.moe.natj.general.ptr.VoidPtr dataBytes,
long dataLayout,
long bytesPerRow,
long bytesPerImage,
MTLRegion region,
MPSImageReadWriteParams featureChannelInfo,
long imageIndex)
readBytes
|
void |
readBytesDataLayoutBytesPerRowRegionFeatureChannelInfoImageIndex(org.moe.natj.general.ptr.VoidPtr dataBytes,
long dataLayout,
long bytesPerRow,
MTLRegion region,
MPSImageReadWriteParams featureChannelInfo,
long imageIndex)
readBytes
|
void |
readBytesDataLayoutImageIndex(org.moe.natj.general.ptr.VoidPtr dataBytes,
long dataLayout,
long imageIndex)
readBytes
|
static boolean |
resolveClassMethod(org.moe.natj.objc.SEL sel) |
static boolean |
resolveInstanceMethod(org.moe.natj.objc.SEL sel) |
long |
resourceSize()
Get the number of bytes used to allocate underyling MTLResources
|
void |
setLabel(java.lang.String value)
[@property] label
|
long |
setPurgeableState(long state)
Set (or query) the purgeability state of a MPSImage
|
static void |
setVersion_static(long aVersion) |
MPSImage |
subImageWithFeatureChannelRange(NSRange range)
Make a sub-image that points to a subset of feature channels in the original
|
static org.moe.natj.objc.Class |
superclass_static() |
void |
synchronizeOnCommandBuffer(MTLCommandBuffer commandBuffer)
Flush the underlying MTLTexture from the device's caches, and invalidate any CPU caches if needed.
|
MTLTexture |
texture()
[@property] texture
|
long |
textureType()
[@property] textureType
|
long |
usage()
[@property] usage
|
static long |
version_static() |
long |
width()
[@property] width
|
void |
writeBytesDataLayoutBytesPerColumnBytesPerRowBytesPerImageRegionFeatureChannelInfoImageIndex(org.moe.natj.general.ptr.ConstVoidPtr dataBytes,
long dataLayout,
long bytesPerColumn,
long bytesPerRow,
long bytesPerImage,
MTLRegion region,
MPSImageReadWriteParams featureChannelInfo,
long imageIndex)
Set the values inside MPSImage with the Buffer passed in.
|
void |
writeBytesDataLayoutBytesPerRowBytesPerImageRegionFeatureChannelInfoImageIndex(org.moe.natj.general.ptr.ConstVoidPtr dataBytes,
long dataLayout,
long bytesPerRow,
long bytesPerImage,
MTLRegion region,
MPSImageReadWriteParams featureChannelInfo,
long imageIndex)
writeBytes
|
void |
writeBytesDataLayoutBytesPerRowRegionFeatureChannelInfoImageIndex(org.moe.natj.general.ptr.ConstVoidPtr dataBytes,
long dataLayout,
long bytesPerRow,
MTLRegion region,
MPSImageReadWriteParams featureChannelInfo,
long imageIndex)
Set the values inside MPSImage with the Buffer passed in.
|
void |
writeBytesDataLayoutImageIndex(org.moe.natj.general.ptr.ConstVoidPtr dataBytes,
long dataLayout,
long imageIndex)
writeBytes
|
accessibilityActivate, accessibilityActivationPoint, accessibilityAssistiveTechnologyFocusedIdentifiers, accessibilityAttributedHint, accessibilityAttributedLabel, accessibilityAttributedUserInputLabels, accessibilityAttributedValue, accessibilityContainerType, accessibilityCustomActions, accessibilityCustomRotors, accessibilityDecrement, accessibilityDragSourceDescriptors, accessibilityDropPointDescriptors, accessibilityElementAtIndex, accessibilityElementCount, accessibilityElementDidBecomeFocused, accessibilityElementDidLoseFocus, accessibilityElementIsFocused, accessibilityElements, accessibilityElementsHidden, accessibilityFrame, accessibilityHint, accessibilityIncrement, accessibilityLabel, accessibilityLanguage, accessibilityNavigationStyle, accessibilityPath, accessibilityPerformEscape, accessibilityPerformMagicTap, accessibilityRespondsToUserInteraction, accessibilityScroll, accessibilityTextualContext, accessibilityTraits, accessibilityUserInputLabels, accessibilityValue, accessibilityViewIsModal, addObserverForKeyPathOptionsContext, attemptRecoveryFromErrorOptionIndex, attemptRecoveryFromErrorOptionIndexDelegateDidRecoverSelectorContextInfo, autoContentAccessingProxy, awakeAfterUsingCoder, awakeFromNib, class_objc, classForCoder, classForKeyedArchiver, copy, dealloc, debugDescription, description, dictionaryWithValuesForKeys, didChangeValueForKey, didChangeValueForKeyWithSetMutationUsingObjects, didChangeValuesAtIndexesForKey, doesNotRecognizeSelector, fileManagerShouldProceedAfterError, fileManagerWillProcessPath, finalize_objc, forwardingTargetForSelector, forwardInvocation, hash, indexOfAccessibilityElement, isAccessibilityElement, isEqual, isKindOfClass, isMemberOfClass, isProxy, methodForSelector, methodSignatureForSelector, mutableArrayValueForKey, mutableArrayValueForKeyPath, mutableCopy, mutableOrderedSetValueForKey, mutableOrderedSetValueForKeyPath, mutableSetValueForKey, mutableSetValueForKeyPath, observationInfo, observeValueForKeyPathOfObjectChangeContext, performSelector, performSelectorInBackgroundWithObject, performSelectorOnMainThreadWithObjectWaitUntilDone, performSelectorOnMainThreadWithObjectWaitUntilDoneModes, performSelectorOnThreadWithObjectWaitUntilDone, performSelectorOnThreadWithObjectWaitUntilDoneModes, performSelectorWithObject, performSelectorWithObjectAfterDelay, performSelectorWithObjectAfterDelayInModes, performSelectorWithObjectWithObject, prepareForInterfaceBuilder, provideImageDataBytesPerRowOrigin_Size_UserInfo, removeObserverForKeyPath, removeObserverForKeyPathContext, replacementObjectForCoder, replacementObjectForKeyedArchiver, respondsToSelector, self, setAccessibilityActivationPoint, setAccessibilityAttributedHint, setAccessibilityAttributedLabel, setAccessibilityAttributedUserInputLabels, setAccessibilityAttributedValue, setAccessibilityContainerType, setAccessibilityCustomActions, setAccessibilityCustomRotors, setAccessibilityDragSourceDescriptors, setAccessibilityDropPointDescriptors, setAccessibilityElements, setAccessibilityElementsHidden, setAccessibilityFrame, setAccessibilityHint, setAccessibilityLabel, setAccessibilityLanguage, setAccessibilityNavigationStyle, setAccessibilityPath, setAccessibilityRespondsToUserInteraction, setAccessibilityTextualContext, setAccessibilityTraits, setAccessibilityUserInputLabels, setAccessibilityValue, setAccessibilityViewIsModal, setIsAccessibilityElement, setNilValueForKey, setObservationInfo, setShouldGroupAccessibilityChildren, setValueForKey, setValueForKeyPath, setValueForUndefinedKey, setValuesForKeysWithDictionary, shouldGroupAccessibilityChildren, superclass, validateValueForKeyError, validateValueForKeyPathError, valueForKey, valueForKeyPath, valueForUndefinedKey, willChangeValueForKey, willChangeValueForKeyWithSetMutationUsingObjects, willChangeValuesAtIndexesForKeypublic static boolean accessInstanceVariablesDirectly()
public static MPSImage alloc()
public static MPSImage allocWithZone(org.moe.natj.general.ptr.VoidPtr zone)
public static boolean automaticallyNotifiesObserversForKey(java.lang.String key)
public static void cancelPreviousPerformRequestsWithTarget(java.lang.Object aTarget)
public static void cancelPreviousPerformRequestsWithTargetSelectorObject(java.lang.Object aTarget,
org.moe.natj.objc.SEL aSelector,
java.lang.Object anArgument)
public static NSArray<java.lang.String> classFallbacksForKeyedArchiver()
public static org.moe.natj.objc.Class classForKeyedUnarchiver()
public static java.lang.String debugDescription_static()
public static java.lang.String description_static()
public static long hash_static()
public static NSObject.Function_instanceMethodForSelector_ret instanceMethodForSelector(org.moe.natj.objc.SEL aSelector)
public static NSMethodSignature instanceMethodSignatureForSelector(org.moe.natj.objc.SEL aSelector)
public static boolean instancesRespondToSelector(org.moe.natj.objc.SEL aSelector)
public static boolean isSubclassOfClass(org.moe.natj.objc.Class aClass)
public static NSSet<java.lang.String> keyPathsForValuesAffectingValueForKey(java.lang.String key)
public static MPSImage new_objc()
public static boolean resolveClassMethod(org.moe.natj.objc.SEL sel)
public static boolean resolveInstanceMethod(org.moe.natj.objc.SEL sel)
public static void setVersion_static(long aVersion)
public static org.moe.natj.objc.Class superclass_static()
public static long version_static()
public MTLDevice device()
The device on which the MPSImage will be used
public long featureChannels()
The number of feature channels per pixel.
public long height()
The formal height of the image in pixels.
public MPSImage initWithDeviceImageDescriptor(MTLDevice device, MPSImageDescriptor imageDescriptor)
Storage to store data needed is allocated lazily on first use of MPSImage or when application calls MPSImage.texture
device - The device that the image will be used. May not be NULL.imageDescriptor - The MPSImageDescriptor. May not be NULL.public MPSImage initWithTextureFeatureChannels(MTLTexture texture, long featureChannels)
Application can let MPS framework allocate texture with properties specified in imageDescriptor using initWithDevice:MPSImageDescriptor API above. However in memory intensive application, you can save memory (and allocation/deallocation time) by using MPSTemporaryImage where MPS framework aggressively reuse memory underlying textures on same command buffer. See MPSTemporaryImage class for details below. However, in certain cases, application developer may want more control on allocation, placement, reusing/recycling of memory backing textures used in application using Metal Heaps API. In this case, application can create MPSImage from pre-allocated texture using initWithTexture:featureChannels.
MTLTextureType of texture can be MTLTextureType2D ONLY if featureChannels <= 4 in which case MPSImage.numberOfImages is set to 1. Else it should be MTLTextureType2DArray with arrayLength == numberOfImage * ((featureChannels + 3)/4). MPSImage.numberOfImages is set to texture.arrayLength / ((featureChannels + 3)/4).
For MTLTextures containing typical image data which application may obtain from MetalKit or other libraries such as that drawn from a JPEG or PNG, featureChannels should be set to number of valid color channel e.g. for RGB data, even thought MTLPixelFormat will be MTLPixelFormatRGBA, featureChannels should be set to 3.
texture - The MTLTexture allocated by the user to be used as backing for MPSImage.featureChannels - Number of feature channels this texture contains.public java.lang.String label()
A string to help identify this object.
public long numberOfImages()
numberOfImages for batch processing
public long pixelFormat()
The MTLPixelFormat of the underlying texture
Note that in some cases, this value may be misleading. For example, float16 data (BFloat16) is sometimes stored in MTLPixelFormatRGBA16Unorm Please consult the featureChannelFormat.
public long pixelSize()
Number of bytes from the first byte of one pixel to the first byte of the next pixel in storage order. (Includes padding.)
public long precision()
The number of bits of numeric precision available for each feature channel.
This is precision, not size. That is, float is 24 bits, not 32. half precision floating-point is 11 bits, not 16. SNorm formats have one less bit of precision for the sign bit, etc. For formats like MTLPixelFormatB5G6R5Unorm it is the precision of the most precise channel, in this case 6. When this information is unavailable, typically compressed formats, 0 will be returned.
public void setLabel(java.lang.String value)
A string to help identify this object.
public long setPurgeableState(long state)
Usage is per [MTLResource setPurgeableState:], except that the MTLTexture might be MPSPurgeableStateAllocationDeferred, which means there is no texture to mark volatile / nonvolatile. Attempts to set purgeability on MTLTextures that have not been allocated will be ignored.
public MTLTexture texture()
The associated MTLTexture object. This is a 2D texture if numberOfImages is 1 and number of feature channels <= 4. It is a 2D texture array otherwise.
To avoid the high cost of premature allocation of the underlying texture, avoid calling this property except when strictly necessary. [MPSCNNKernel encode...] calls typically cause their arguments to become allocated. Likewise, MPSImages initialized with -initWithTexture: featureChannels: have already been allocated.
public long textureType()
The type of the underlying texture, typically MTLTextureType2D or MTLTextureType2DArray
public long usage()
Description of texture usage.
public long width()
The formal width of the image in pixels.
public static MPSImageAllocator defaultAllocator()
public void readBytesDataLayoutBytesPerRowRegionFeatureChannelInfoImageIndex(org.moe.natj.general.ptr.VoidPtr dataBytes,
long dataLayout,
long bytesPerRow,
MTLRegion region,
MPSImageReadWriteParams featureChannelInfo,
long imageIndex)
Get the values inside MPSImage and put them in the Buffer passed in.
Use the enum to set data is coming in with what order. The data type will be determined by the pixelFormat defined in the Image Descriptor.
dataBytes - The array allocated by the user to be used to put data from MPSImage, the length should be
imageWidth * imageHeight * numberOfFeatureChannels and dataType should be inferred from pixelFormat
defined in the Image Descriptor.dataLayout - The enum tells how to layout MPS data in the buffer.bytesPerRow - Bytes to stride to point to next row(pixel just below current one) in the user buffer.featureChannelInfo - information user fills in to write to a set of feature channels in the imageimageIndex - Image index in MPSImage to write to.region - region of the MPSImage to read from. A region is a structure with the origin in the Image from which to start
reading values and a size which represents the width and height of the rectangular region to read from.
The z direction denotes the number of images, thus for 1 image, origin.z = 0 and size.depth = 1public void readBytesDataLayoutImageIndex(org.moe.natj.general.ptr.VoidPtr dataBytes,
long dataLayout,
long imageIndex)
Get the values inside MPSImage and put them in the Buffer passed in.
Use the enum to set data is coming in with what order. The data type will be determined by the pixelFormat defined in the Image Descriptor. Region is full image, buffer width and height is same as MPSImage width and height.
dataBytes - The array allocated by the user to be used to put data from MPSImage, the length should be
imageWidth * imageHeight * numberOfFeatureChannels and dataType should be inferred from pixelFormat
defined in the Image Descriptor.dataLayout - The enum tells how to layout MPS data in the buffer.imageIndex - Image index in MPSImage to read from.public void writeBytesDataLayoutBytesPerRowRegionFeatureChannelInfoImageIndex(org.moe.natj.general.ptr.ConstVoidPtr dataBytes,
long dataLayout,
long bytesPerRow,
MTLRegion region,
MPSImageReadWriteParams featureChannelInfo,
long imageIndex)
This method is used to copy data from the storage provided by dataBytes to the MPSImage. The ordering of data in your dataBytes buffer is given by dataLayout. Each image may be stored as either a series of planar images (a series of single WxH images, one per feature channel) or a single chunky image, WxHxfeature_channels. BytesPerRow and BytesPerImage are there to allow some padding between successive rows and successive images. No padding is allowed between successive feature channels.
dataBytes - The array allocated by the user to be used to put data from MPSImage, the length should be
imageWidth * imageHeight * numberOfFeatureChannels and dataType should be inferred from pixelFormat
defined in the Image Descriptor.dataLayout - The enum tells how to layout MPS data in the buffer.bytesPerRow - Bytes to stride to point to next row(pixel just below current one) in the user buffer.region - region of the MPSImage to write to. A region is a structure with the origin in the Image from which to start
writing values and a size which represents the width and height of the rectangular region to write in.
The z direction denotes the number of images, thus for 1 image, origin.z = 0 and size.depth = 1featureChannelInfo - information user fills in to read from a set of feature channels in the imageimageIndex - Image index in MPSImage to write to.public void writeBytesDataLayoutImageIndex(org.moe.natj.general.ptr.ConstVoidPtr dataBytes,
long dataLayout,
long imageIndex)
Set the values inside MPSImage with the Buffer passed in.
Use the enum to set data is coming in with what order. The data type will be determined by the pixelFormat defined in the Image Descriptor. Region is full image, buffer width and height is same as MPSImage width and height.
dataBytes - The array allocated by the user to be used to put data from MPSImage, the length should be
imageWidth * imageHeight * numberOfFeatureChannels and dataType should be inferred from pixelFormat
defined in the Image Descriptor.dataLayout - The enum tells how to layout MPS data in the buffer.imageIndex - Image index in MPSImage to write to.public long featureChannelFormat()
The true encoding of the feature channels
public MPSImage initWithParentImageSliceRangeFeatureChannels(MPSImage parent, NSRange sliceRange, long featureChannels)
Generally, you should call -batchRepresentation or -subImageWithFeatureChannelRange instead because they are safer. This is provided so that these interfaces will work with your MPSImage subclass.
parent - The parent image that owns the texture. It may be a sub-image.sliceRange - The range of MTLTexture2dArray slices to be included in the sub-imagefeatureChannels - The number of feature channels in the new image. The number of images
is inferred.public MPSImage parent()
This will point to the original image if this image was created using -batchRepresentation, -batchRepresentationWithRange: or -subImageWithFeatureChannelRange:.
public void readBytesDataLayoutBytesPerRowBytesPerImageRegionFeatureChannelInfoImageIndex(org.moe.natj.general.ptr.VoidPtr dataBytes,
long dataLayout,
long bytesPerRow,
long bytesPerImage,
MTLRegion region,
MPSImageReadWriteParams featureChannelInfo,
long imageIndex)
Get the values inside MPSImage and put them in the Buffer passed in.
This method is used to copy data from the MPSImage to the storage provided by dataBytes. The ordering of data in your dataBytes buffer is given by dataLayout. Each image may be stored as either a series of planar images (a series of single WxH images, one per feature channel) or a single chunky image, WxHxfeature_channels. BytesPerRow and BytesPerImage are there to allow some padding between successive rows and successive images. No padding is allowed between successive feature channels.
BUG: Prior to MacOS 10.15, iOS/tvOS 13.0, incorrect behavior may be observed if region.size.depth != 1 or if bytesPerRow allowed for unused padding between rows. BUG: To provide for full capability to extract and insert content from arbitrarily sized buffers, there should also be a featureChannelStride in addition to bytesPerRow and bytesPerImage. With the current design, when we finish the last feature channel, the next byte will contain the 0th feature channel for the next texel or slice, depending on packing order. This method can not be used to modify some but not all of the feature channels in an image.
dataBytes - The array allocated by the user to be used to put data from MPSImage, the length should be
imageWidth * imageHeight * numberOfFeatureChannels and dataType should be inferred from pixelFormat
defined in the Image Descriptor.dataLayout - The enum tells how to layout MPS data in the buffer.bytesPerRow - Bytes to stride to point to next row(pixel just below current one) in the user buffer.bytesPerImage - Bytes to stride to point to next dataBytes image. See region.size.depth for image count.featureChannelInfo - information user fills in to write to a set of feature channels in the imageimageIndex - Image index in MPSImage to write to.region - region of the MPSImage to read from. A region is a structure with the origin in the Image from which to start
reading values and a size which represents the width and height of the rectangular region to read from.
The z direction denotes the number of images, thus for 1 image, origin.z = 0 and size.depth = 1public long resourceSize()
This is the size of the backing store of underlying MTLResources. It does not include all storage used by the object, for example the storage used to hold the MPSImage instantiation and MTLTexture is not included. It only measures the size of the allocation used to hold the texels in the image. This value is subject to change between different devices and operating systems.
Except when -initWithTexture:featureChannels: is used, most MPSImages (including MPSTemporaryImages) are allocated without a backing store. The backing store is allocated lazily when it is needed, typically when the .texture property is called. Consequently, in most cases, it should be inexpensive to make a MPSImage to see how much memory it will need, and release it if it is too large.
This method may fail in certain circumstances, such as when the MPSImage is created with -initWithTexture:featureChannels:, in which case 0 will be returned. 0 will also be returned if it is a sub-image or sub-batch (.parent is not nil).
public MPSImage subImageWithFeatureChannelRange(NSRange range)
This makes a MPSImage that points to a feature channel subregion within the original image. It is a much cheaper form of the slice operator in both memory usage and GPU time, and should be used instead when the slice operator does not need to operate out of place and the feature channel range is a multiple of 4.
If the original is a temporary image, the result will be a temporary image. It will hold 1 readCount on the original. When the readCount drops to 0, it will decrement the appropriate counter on the parent.
range - A range describing the sub-range within the MPSImage
to make the subImage within. The location and length
must be multiples of 4. If the length is too big, it
will be reduced to fit in the image.public void synchronizeOnCommandBuffer(MTLCommandBuffer commandBuffer)
This will call [id
commandBuffer - The commandbuffer on which to synchronizepublic void writeBytesDataLayoutBytesPerColumnBytesPerRowBytesPerImageRegionFeatureChannelInfoImageIndex(org.moe.natj.general.ptr.ConstVoidPtr dataBytes,
long dataLayout,
long bytesPerColumn,
long bytesPerRow,
long bytesPerImage,
MTLRegion region,
MPSImageReadWriteParams featureChannelInfo,
long imageIndex)
This method is used to copy data from the storage provided by dataBytes to the MPSImage. The ordering of data in your dataBytes buffer is given by dataLayout. Each image may be stored as either a series of planar images (a series of single WxH images, one per feature channel) or a single chunky image, WxHxfeature_channels. BytesPerRow and BytesPerImage are there to allow some padding between successive rows and successive images. No padding is allowed between successive feature channels.
dataBytes - The array allocated by the user to be used to put data from MPSImage, the length should be
imageWidth * imageHeight * numberOfFeatureChannels and dataType should be inferred from pixelFormat
defined in the Image Descriptor.dataLayout - The enum tells how to layout MPS data in the buffer.bytesPerColumn - This is the stride in bytes from W[0] to W[1], for both HWC and CHW orderings in the buffer pointed to by dataBytes.bytesPerRow - Bytes to stride to point to next row(pixel just below current one, i.e. H[0] to H[1]) in the buffer pointed to by dataBytes.bytesPerImage - This is the stride in bytes from image[0] to image[1] im the buffer pointed to by dataBytes.region - region of the MPSImage to write to. A region is a structure with the origin in the Image from which to start
writing values and a size which represents the width and height of the rectangular region to write in.
The z direction denotes the number of images, thus for 1 image, origin.z = 0 and size.depth = 1featureChannelInfo - information user fills in to read from a set of feature channels in the imageimageIndex - Image index in MPSImage to write to.public void writeBytesDataLayoutBytesPerRowBytesPerImageRegionFeatureChannelInfoImageIndex(org.moe.natj.general.ptr.ConstVoidPtr dataBytes,
long dataLayout,
long bytesPerRow,
long bytesPerImage,
MTLRegion region,
MPSImageReadWriteParams featureChannelInfo,
long imageIndex)
Set the values inside MPSImage with the Buffer passed in.
Use the enum to set data is coming in with what order. The data type will be determined by the pixelFormat defined in the Image Descriptor.
BUG: Prior to MacOS 10.15, iOS/tvOS 13.0, incorrect behavior may be observed if region.size.depth != 1 or if bytesPerRow allowed for unused padding between rows. BUG: To provide for full capability to extract and insert content from arbitrarily sized buffers, there should also be a featureChannelStride in addition to bytesPerRow and bytesPerImage. With the current design, when we finish the last feature channel, the next byte will contain the 0th feature channel for the next texel or slice, depending on packing order. This method can not be used to modify some but not all of the feature channels in an image.
dataBytes - The array allocated by the user to be used to put data from MPSImage, the length should be
imageWidth * imageHeight * numberOfFeatureChannels and dataType should be inferred from pixelFormat
defined in the Image Descriptor.dataLayout - The enum tells how to layout MPS data in the buffer.bytesPerRow - Bytes to stride to point to next row(pixel just below current one) in the user buffer.bytesPerImage - Bytes to stride to point to next dataBytes image. See region.size.depth for image count.region - region of the MPSImage to write to. A region is a structure with the origin in the Image from which to start
writing values and a size which represents the width and height of the rectangular region to write in.
The z direction denotes the number of images, thus for 1 image, origin.z = 0 and size.depth = 1featureChannelInfo - information user fills in to read from a set of feature channels in the imageimageIndex - Image index in MPSImage to write to.