Struct MPSImage 

pub struct MPSImage { /* private fields */ }

Available on crate feature MPSImage only.

Dependencies: This depends on Metal.framework

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

              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???

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 25=10 and number of destination slices will be 44=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.

See also Apple’s documentation

Implementations

impl MPSImage

pub unsafe fn batch_increment_read_count( batch: &MPSImageBatch, amount: NSInteger, ) -> NSUInteger

Available on crate feature MPSCore only.

raise or lower the readcount of a batch by a set amount

In some circumstances, a MPSImage may appear in a MPSImageBatch multiple times. This is particularly common when the MPSImage serves as an accumulator across the entire batch, such as when accumulating gradients for convolution weight update or batch statistics for batch normalization. A naive function would then end up incrementing the state multiple times, probably leading to an error.

MPSImageBatchIncrementReadCount() will efficiently increment the readCounts of each object in the batch only once, avoiding this problem. Non-temporary images and images with readCount already 0 will be ignored.

CAUTION: At many places in MPS, the framework assumes all images in the batch have the same characteristics, such as MPSImageFeatureChannelFormat. At times, for example, it is necessary to patch in a special version of the kernel to handle BFloat16 or another characteristic. When this happens, the kernel generally can’t respond correctly when some images in a batch have that characteristic and some do not, because the special case handling code is hard compiled in. For this reason, all images in a batch should be constructed from the same list of descriptor parameters.

Parameter batch: The MPSImageBatch to increment

Parameter amount: The value to add to the read count for each unique image in the batch

Returns: The number of different images in the batch

pub unsafe fn batch_synchronize( batch: &MPSImageBatch, cmd_buf: &ProtocolObject<dyn MTLCommandBuffer>, )

Available on crate feature MPSCore only.

Call [MTLBlitEncoder synchronizeResource:] on unique resources

pub unsafe fn batch_resource_size(batch: &MPSImageBatch) -> NSUInteger

Available on crate feature MPSCore only.

Call [MTLBlitEncoder resourceSize] on unique resources and return sum

pub unsafe fn batch_iterate( batch: &MPSImageBatch, iterator_block: &DynBlock<dyn Fn(NonNull<MPSImage>, NSUInteger) -> NSInteger>, ) -> NSInteger

Available on crate features MPSCore and block2 only.

Iterate over unique images in the batch

This function looks only at image address to determine uniqueness. The same texture stored in different MPSImages would be considered not unique.

Parameter batch: The image batch

Parameter iteratorBlock: Callback block to execute once for each unique image. Return a value greater than NSIntegerMin to terminate early. The index gives the first position in the batch where the image appears. Behavior is undefined if MPSImageBatchIterate is called recursively on the same images.

Returns: The value returned by the iterator block for the last image on which it ran

impl MPSImage

pub unsafe fn defaultAllocator() -> Retained<ProtocolObject<dyn MPSImageAllocator>>

Available on crate feature MPSCore only.

Get a well known MPSImageAllocator that makes MPSImages

pub unsafe fn device(&self) -> Retained<ProtocolObject<dyn MTLDevice>>

Available on crate feature MPSCore only.

The device on which the MPSImage will be used

pub unsafe fn width(&self) -> NSUInteger

Available on crate feature MPSCore only.

The formal width of the image in pixels.

pub unsafe fn height(&self) -> NSUInteger

Available on crate feature MPSCore only.

The formal height of the image in pixels.

pub unsafe fn featureChannels(&self) -> NSUInteger

Available on crate feature MPSCore only.

The number of feature channels per pixel.

pub unsafe fn numberOfImages(&self) -> NSUInteger

Available on crate feature MPSCore only.

numberOfImages for batch processing

pub unsafe fn textureType(&self) -> MTLTextureType

Available on crate feature MPSCore only.

The type of the underlying texture, typically MTLTextureType2D or MTLTextureType2DArray

pub unsafe fn pixelFormat(&self) -> MTLPixelFormat

Available on crate feature MPSCore only.

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.

pub unsafe fn precision(&self) -> NSUInteger

Available on crate feature MPSCore only.

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.

pub unsafe fn usage(&self) -> MTLTextureUsage

Available on crate feature MPSCore only.

Description of texture usage.

pub unsafe fn featureChannelFormat(&self) -> MPSImageFeatureChannelFormat

Available on crate features MPSCore and MPSCoreTypes only.

The true encoding of the feature channels

pub unsafe fn pixelSize(&self) -> usize

Available on crate feature MPSCore only.

Number of bytes from the first byte of one pixel to the first byte of the next pixel in storage order. (Includes padding.)

pub unsafe fn texture(&self) -> Retained<ProtocolObject<dyn MTLTexture>>

Available on crate feature MPSCore only.

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.

pub unsafe fn label(&self) -> Option<Retained<NSString>>

Available on crate feature MPSCore only.

A string to help identify this object.

pub unsafe fn setLabel(&self, label: Option<&NSString>)

Available on crate feature MPSCore only.

Setter for label.

This is copied when set.

pub unsafe fn parent(&self) -> Option<Retained<MPSImage>>

Available on crate feature MPSCore only.

The MPSImage from which this MPSImage was derived. Otherwise nil.

This will point to the original image if this image was created using -batchRepresentation, -batchRepresentationWithRange: or -subImageWithFeatureChannelRange:.

pub unsafe fn initWithDevice_imageDescriptor( this: Allocated<Self>, device: &ProtocolObject<dyn MTLDevice>, image_descriptor: &MPSImageDescriptor, ) -> Retained<Self>

Available on crate feature MPSCore only.

Initialize an empty image object

Parameter device: The device that the image will be used. May not be NULL.

Parameter imageDescriptor: The MPSImageDescriptor. May not be NULL.

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

Storage to store data needed is allocated lazily on first use of MPSImage or when application calls MPSImage.texture

pub unsafe fn initWithParentImage_sliceRange_featureChannels( this: Allocated<Self>, parent: &MPSImage, slice_range: NSRange, feature_channels: NSUInteger, ) -> Retained<Self>

Available on crate feature MPSCore only.

Use -batchRepresentation or -subImageWithFeatureChannelRange instead

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.

Parameter parent: The parent image that owns the texture. It may be a sub-image.

Parameter sliceRange: The range of MTLTexture2dArray slices to be included in the sub-image

Parameter featureChannels: The number of feature channels in the new image. The number of images is inferred.

Returns: A MPSImage that references a subregion of the texel storage in parent instead of using its own storage.

pub unsafe fn initWithTexture_featureChannels( this: Allocated<Self>, texture: &ProtocolObject<dyn MTLTexture>, feature_channels: NSUInteger, ) -> Retained<Self>

Available on crate feature MPSCore only.

Initialize an MPSImage object using Metal texture. Metal texture has been created by user for specific number of feature channels and number of images.

Parameter texture: The MTLTexture allocated by the user to be used as backing for MPSImage.

Parameter featureChannels: Number of feature channels this texture contains.

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

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.

Safety

• texture may need to be synchronized.
• texture may be unretained, you must ensure it is kept alive while in use.

pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>

Available on crate feature MPSCore only.

pub unsafe fn batchRepresentationWithSubRange( &self, sub_range: NSRange, ) -> Retained<MPSImageBatch>

Available on crate feature MPSCore only.

Make a representation of a MPSImage (batch) as a MPSImageBatch

Before the MPSImageBatch was introduced, several images could be concatenated into a MPSImage as multiple image slices in a MTLTexture2DArray to make a image batch. If the image contained more than 4 feature channels, then each image would have round_up( feature channels / 4) slices and the total number of slices in the MPSImage would be slices * number of images.

Because many devices can operate on texture arrays of no more than 2048 slices, storage in this format is limited. For example in InceptionV3, 2048 feature channels at its widest point, the largest batch size that can be processed in this way is 4, well under commonly accepted practice for training. Consequently, the older batching style is deprecated and the MPSImageBatch is introduced. It is also easier to manage sub-batches and to concatenate sub-batches for memory management with the MPSImageBatch, so this format is favored going forward.

To facilitate forward migration, this method will prepare an array of MPSImages that each point to the appropriate set of slices in storage for the original image. Since they share storage, writes to the parent will alter the content of the children, and vice versa.

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.

This is a much cheaper form of the slice operator, and should be used instead when the slice operator does not need to operate out of place.

Parameter subRange: The range of images in the original image from which the batch will be derived.

Returns: A MPSImageBatch referencing a subregion of the original batch image.

pub unsafe fn batchRepresentation(&self) -> Retained<MPSImageBatch>

Available on crate feature MPSCore only.

Make a MPSImageBatch that points to the individual images in the MPSImage

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.

Returns: A MPSImageBatch aliasing the texel storage in the original batch image

pub unsafe fn subImageWithFeatureChannelRange( &self, range: NSRange, ) -> Retained<MPSImage>

Available on crate feature MPSCore only.

pub unsafe fn resourceSize(&self) -> NSUInteger

Available on crate feature MPSCore only.

Get the number of bytes used to allocate underyling MTLResources

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).

pub unsafe fn setPurgeableState( &self, state: MPSPurgeableState, ) -> MPSPurgeableState

Available on crate feature MPSCore only.

Set (or query) the purgeability state of a MPSImage

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.

pub unsafe fn readBytes_dataLayout_bytesPerRow_region_featureChannelInfo_imageIndex( &self, data_bytes: NonNull<c_void>, data_layout: MPSDataLayout, bytes_per_row: NSUInteger, region: MTLRegion, feature_channel_info: MPSImageReadWriteParams, image_index: NSUInteger, )

Available on crate feature MPSCore only.

Get the values inside MPSImage and put them in the Buffer passed in.

Parameter 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.

Parameter dataLayout: The enum tells how to layout MPS data in the buffer.

Parameter bytesPerRow: Bytes to stride to point to next row(pixel just below current one) in the user buffer.

Parameter featureChannelInfo: information user fills in to write to a set of feature channels in the image

Parameter imageIndex: Image index in MPSImage to write to.

Parameter 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 = 1

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.

Safety

data_bytes must be a valid pointer.

pub unsafe fn writeBytes_dataLayout_bytesPerRow_region_featureChannelInfo_imageIndex( &self, data_bytes: NonNull<c_void>, data_layout: MPSDataLayout, bytes_per_row: NSUInteger, region: MTLRegion, feature_channel_info: MPSImageReadWriteParams, image_index: NSUInteger, )

Available on crate feature MPSCore only.

Set the values inside MPSImage with the Buffer passed in.

Parameter 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.

Parameter dataLayout: The enum tells how to layout MPS data in the buffer.

Parameter bytesPerRow: Bytes to stride to point to next row(pixel just below current one) in the user buffer.

Parameter 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 = 1

Parameter featureChannelInfo: information user fills in to read from a set of feature channels in the image

Parameter imageIndex: Image index in MPSImage to write to.

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.

Safety

data_bytes must be a valid pointer.

pub unsafe fn writeBytes_dataLayout_bytesPerColumn_bytesPerRow_bytesPerImage_region_featureChannelInfo_imageIndex( &self, data_bytes: NonNull<c_void>, data_layout: MPSDataLayout, bytes_per_column: NSUInteger, bytes_per_row: NSUInteger, bytes_per_image: NSUInteger, region: MTLRegion, feature_channel_info: MPSImageReadWriteParams, image_index: NSUInteger, )

Available on crate feature MPSCore only.

Set the values inside MPSImage with the Buffer passed in.

Parameter 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.

Parameter dataLayout: The enum tells how to layout MPS data in the buffer.

Parameter 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.

Parameter 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.

Parameter bytesPerImage: This is the stride in bytes from image[0] to image[1] im the buffer pointed to by dataBytes.

Parameter 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 = 1

Parameter featureChannelInfo: information user fills in to read from a set of feature channels in the image

Parameter imageIndex: Image index in MPSImage to write to.

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.

Safety

data_bytes must be a valid pointer.

pub unsafe fn readBytes_dataLayout_bytesPerRow_bytesPerImage_region_featureChannelInfo_imageIndex( &self, data_bytes: NonNull<c_void>, data_layout: MPSDataLayout, bytes_per_row: NSUInteger, bytes_per_image: NSUInteger, region: MTLRegion, feature_channel_info: MPSImageReadWriteParams, image_index: NSUInteger, )

Available on crate feature MPSCore only.

Get the values inside MPSImage and put them in the Buffer passed in.

Parameter 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.

Parameter dataLayout: The enum tells how to layout MPS data in the buffer.

Parameter bytesPerRow: Bytes to stride to point to next row(pixel just below current one) in the user buffer.

Parameter bytesPerImage: Bytes to stride to point to next dataBytes image. See region.size.depth for image count.

Parameter featureChannelInfo: information user fills in to write to a set of feature channels in the image

Parameter imageIndex: Image index in MPSImage to write to.

Parameter 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 = 1

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.

Safety

data_bytes must be a valid pointer.

pub unsafe fn writeBytes_dataLayout_bytesPerRow_bytesPerImage_region_featureChannelInfo_imageIndex( &self, data_bytes: NonNull<c_void>, data_layout: MPSDataLayout, bytes_per_row: NSUInteger, bytes_per_image: NSUInteger, region: MTLRegion, feature_channel_info: MPSImageReadWriteParams, image_index: NSUInteger, )

Available on crate feature MPSCore only.

Set the values inside MPSImage with the Buffer passed in.

Parameter 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.

Parameter dataLayout: The enum tells how to layout MPS data in the buffer.

Parameter bytesPerRow: Bytes to stride to point to next row(pixel just below current one) in the user buffer.

Parameter bytesPerImage: Bytes to stride to point to next dataBytes image. See region.size.depth for image count.

Parameter 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 = 1

Parameter featureChannelInfo: information user fills in to read from a set of feature channels in the image

Parameter imageIndex: Image index in MPSImage to write to.

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.

Safety

data_bytes must be a valid pointer.

pub unsafe fn readBytes_dataLayout_imageIndex( &self, data_bytes: NonNull<c_void>, data_layout: MPSDataLayout, image_index: NSUInteger, )

Available on crate feature MPSCore only.

Get the values inside MPSImage and put them in the Buffer passed in.

Parameter 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.

Parameter dataLayout: The enum tells how to layout MPS data in the buffer.

Parameter imageIndex: Image index in MPSImage to read from.

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.

Safety

data_bytes must be a valid pointer.

pub unsafe fn writeBytes_dataLayout_imageIndex( &self, data_bytes: NonNull<c_void>, data_layout: MPSDataLayout, image_index: NSUInteger, )

Available on crate feature MPSCore only.

Set the values inside MPSImage with the Buffer passed in.

Parameter 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.

Parameter dataLayout: The enum tells how to layout MPS data in the buffer.

Parameter imageIndex: Image index in MPSImage to write to.

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.

Safety

data_bytes must be a valid pointer.

pub unsafe fn synchronizeOnCommandBuffer( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, )

Available on crate feature MPSCore only.

Flush the underlying MTLTexture from the device’s caches, and invalidate any CPU caches if needed.

This will call [id <MTLBlitEncoder

synchronizeResource: ] on the image’s MTLTexture, if any. This is necessary for all MTLStorageModeManaged resources. For other resources, including temporary resources (these are all MTLStorageModePrivate), and textures that have not yet been allocated, nothing is done. It is more efficient to use this method than to attempt to do this yourself with the texture property.

Parameter commandBuffer: The commandbuffer on which to synchronize

impl MPSImage

Methods declared on superclass NSObject.

pub unsafe fn new() -> Retained<Self>

Available on crate feature MPSCore only.

Methods from Deref<Target = NSObject>

pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !

Handle messages the object doesn’t recognize.

See Apple’s documentation for details.

Methods from Deref<Target = AnyObject>

pub fn class(&self) -> &'static AnyClass

Dynamically find the class of this object.

Panics

May panic if the object is invalid (which may be the case for objects returned from unavailable init/new methods).

Example

Check that an instance of NSObject has the precise class NSObject.

use objc2::ClassType;
use objc2::runtime::NSObject;

let obj = NSObject::new();
assert_eq!(obj.class(), NSObject::class());

pub unsafe fn get_ivar<T>(&self, name: &str) -> &T

where T: Encode,

👎Deprecated: this is difficult to use correctly, use Ivar::load instead.

Use Ivar::load instead.

Safety

The object must have an instance variable with the given name, and it must be of type T.

See Ivar::load_ptr for details surrounding this.

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: DowncastTarget,

Attempt to downcast the object to a class of type T.

This is the reference-variant. Use Retained::downcast if you want to convert a retained object to another type.

Mutable classes

Some classes have immutable and mutable variants, such as NSString and NSMutableString.

When some Objective-C API signature says it gives you an immutable class, it generally expects you to not mutate that, even though it may technically be mutable “under the hood”.

So using this method to convert a NSString to a NSMutableString, while not unsound, is generally frowned upon unless you created the string yourself, or the API explicitly documents the string to be mutable.

See Apple’s documentation on mutability and on isKindOfClass: for more details.

Generic classes

Objective-C generics are called “lightweight generics”, and that’s because they aren’t exposed in the runtime. This makes it impossible to safely downcast to generic collections, so this is disallowed by this method.

You can, however, safely downcast to generic collections where all the type-parameters are AnyObject.

Panics

This works internally by calling isKindOfClass:. That means that the object must have the instance method of that name, and an exception will be thrown (if CoreFoundation is linked) or the process will abort if that is not the case. In the vast majority of cases, you don’t need to worry about this, since both root objects NSObject and NSProxy implement this method.

Examples

Cast an NSString back and forth from NSObject.

use objc2::rc::Retained;
use objc2_foundation::{NSObject, NSString};

let obj: Retained<NSObject> = NSString::new().into_super();
let string = obj.downcast_ref::<NSString>().unwrap();
// Or with `downcast`, if we do not need the object afterwards
let string = obj.downcast::<NSString>().unwrap();

Try (and fail) to cast an NSObject to an NSString.

use objc2_foundation::{NSObject, NSString};

let obj = NSObject::new();
assert!(obj.downcast_ref::<NSString>().is_none());

Try to cast to an array of strings.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);
// This is invalid and doesn't type check.
let arr = arr.downcast_ref::<NSArray<NSString>>();

This fails to compile, since it would require enumerating over the array to ensure that each element is of the desired type, which is a performance pitfall.

Downcast when processing each element instead.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);

for elem in arr {
    if let Some(data) = elem.downcast_ref::<NSString>() {
        // handle `data`
    }
}

Trait Implementations

impl AsRef<AnyObject> for MPSImage

Available on crate feature MPSCore only.

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<MPSImage> for MPSImage

Available on crate feature MPSCore only.

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<MPSImage> for MPSTemporaryImage

Available on crate feature MPSCore only.

fn as_ref(&self) -> &MPSImage

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<NSObject> for MPSImage

Available on crate feature MPSCore only.

fn as_ref(&self) -> &NSObject

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<AnyObject> for MPSImage

Available on crate feature MPSCore only.

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<MPSImage> for MPSTemporaryImage

Available on crate feature MPSCore only.

fn borrow(&self) -> &MPSImage

Immutably borrows from an owned value.

impl Borrow<NSObject> for MPSImage

Available on crate feature MPSCore only.

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for MPSImage

Available on crate feature MPSCore only.

const NAME: &'static str = "MPSImage"

The name of the Objective-C class that this type represents.

type Super = NSObject

The superclass of this class.

type ThreadKind = <<MPSImage as ClassType>::Super as ClassType>::ThreadKind

Whether the type can be used from any thread, or from only the main thread.

fn class() -> &'static AnyClass

Get a reference to the Objective-C class that this type represents.

fn as_super(&self) -> &Self::Super

Get an immutable reference to the superclass.

impl Debug for MPSImage

Available on crate feature MPSCore only.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for MPSImage

Available on crate feature MPSCore only.

type Target = NSObject

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for MPSImage

Available on crate feature MPSCore only.

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Message for MPSImage

Available on crate feature MPSCore only.

fn retain(&self) -> Retained<Self>

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for MPSImage

Available on crate feature MPSCore only.

fn isEqual(&self, other: Option<&AnyObject>) -> bool

where Self: Sized + Message,

Check whether the object is equal to an arbitrary other object.

fn hash(&self) -> usize

where Self: Sized + Message,

An integer that can be used as a table address in a hash table structure.

fn isKindOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of the class, or one of its subclasses.

fn is_kind_of<T>(&self) -> bool

where T: ClassType, Self: Sized + Message,

👎Deprecated: use isKindOfClass directly, or cast your objects with AnyObject::downcast_ref

Check if the object is an instance of the class type, or one of its subclasses.

fn isMemberOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of a specific class, without checking subclasses.

fn respondsToSelector(&self, aSelector: Sel) -> bool

where Self: Sized + Message,

Check whether the object implements or inherits a method with the given selector.

fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool

where Self: Sized + Message,

Check whether the object conforms to a given protocol.

fn description(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object.

fn debugDescription(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object to use when debugging.

fn isProxy(&self) -> bool

where Self: Sized + Message,

Check whether the receiver is a subclass of the NSProxy root class instead of the usual NSObject.

fn retainCount(&self) -> usize

where Self: Sized + Message,

The reference count of the object.

impl PartialEq for MPSImage

Available on crate feature MPSCore only.

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RefEncode for MPSImage

Available on crate feature MPSCore only.

const ENCODING_REF: Encoding = <NSObject as ::objc2::RefEncode>::ENCODING_REF

The Objective-C type-encoding for a reference of this type.

impl DowncastTarget for MPSImage

Available on crate feature MPSCore only.

impl Eq for MPSImage

Available on crate feature MPSCore only.