Struct MPSCNNLoss 

pub struct MPSCNNLoss { /* private fields */ }

Available on crate features MPSCNNKernel and MPSCNNLoss and MPSCore and MPSKernel only.

Dependencies: This depends on Metal.framework.

The MPSCNNLoss filter is only used for training. This filter performs both the forward and backward pass computations. Specifically, it computes the loss between the input (predictions) and target data (labels) and the loss gradient. The loss value can be a 1 x 1 x 1 image containing a scalar loss value or an image (of the same size as the input source image) with per feature channel losses. The loss value is used to determine whether to continue the training operation or to terminate it, once satisfactory results are achieved. The loss gradient is the first gradient computed for the backward pass and serves as input to the next gradient filter (in the backward direction).

The MPSCNNLoss filter is created with a MPSCNNLossDescriptor describing the type of a loss filter and the type of a reduction to use for computing the overall loss.

The MPSCNNLoss filter takes the output of the inference pass (predictions) as input. It also requires the target data (labels) and optionally, weights for the labels. If per-label weights are not supplied, there is an option to use a single weight value by setting the ‘weight’ properly on the MPSCNNLossDescriptor object. The labels and optional weights need to be supplied by the user using the MPSCNNLossLabels object. The labels and weights are described via the MPSCNNLossDataDescriptor objects, which are in turn used to initialize the MPSCNNLossLabels object.

If the specified reduction operation is MPSCNNReductionTypeNone, the destinationImage should be at least as large as the specified clipRect. The destinationImage will then contain per-element losses. Otherse, a reduction operation will be performed, according to the specified reduction type, and the filter will return a scalar value containing the overall loss. For more information on the available reduction types, see MPSCNNTypes.h. Also see MPSCNNLossDescriptor for the description of optional parameters.

Here is a code example:

// Setup MPSCNNLossDataDescriptor* labelsDescriptor = [MPSCNNLossDataDescriptor cnnLossDataDescriptorWithData: labelsData layout: MPSDataLayoutHeightxWidthxFeatureChannels size: labelsDataSize]; MPSCNNLossLabels* labels = [[MPSCNNLossLabels alloc] initWithDevice: device labelsDescriptor: labelsDescriptor]; MPSCNNLossDescriptor lossDescriptor = [MPSCNNLossDescriptor cnnLossDescriptorWithType: (MPSCNNLossType)MPSCNNLossTypeMeanAbsoluteError reductionType: (MPSCNNReductionType)MPSCNNReductionTypeSum]; MPSCNNLoss lossFilter = [[MPSCNNLoss alloc] initWithDevice: device lossDescriptor: lossDescriptor];

// Encode loss filter. // The sourceImage is the output of a previous layer, for example, the SoftMax layer. The lossGradientsImage // is the sourceGradient input image to the first gradient layer (in the backward direction), for example, // the SoftMax gradient filter. [lossFilter encodeToCommandBuffer: commandBuffer sourceImage: sourceImage labels: labels destinationImage: lossGradientsImage];

// In order to guarantee that the loss image data is correctly synchronized for CPU side access, // it is the application’s responsibility to call the [labels synchronizeOnCommandBuffer:] // method before accessing the loss image data. [labels synchronizeOnCommandBuffer:commandBuffer]; MPSImage* lossImage = [labels lossImage];

For predictions (y) and labels (t), the available loss filter types are the following:

Mean Absolute Error loss filter. This filter measures the absolute error of the element-wise difference between the predictions and labels. This loss function is computed according to the following formulas: Compute losses: losses = |y - t| Compute weighted losses: weighted_losses = weight(s) * losses Compute overall loss: loss = reduce(weighted_losses, reductionType)

Mean Squared Error loss filter. This filter measures the squared error of the element-wise difference between the predictions and labels. This loss function is computed according to the following formulas: Compute losses: losses = (y - t)^2 Compute weighted losses: weighted_losses = weight(s) * losses Compute overall loss: loss = reduce(weighted_losses, reductionType)

SoftMax Cross Entropy loss filter. This loss filter is applied element-wise. This loss filter combines the LogSoftMax and Negative Log Likelihood operations in a single filter. It is useful for training a classification problem with multiple classes. This loss function is computed according to the following formulas: Compute losses: losses = -t * LogSoftMax(y) Compute weighted losses: weighted_losses = weight(s) * losses Compute overall loss: loss = reduce(weighted_losses, reductionType) If reductionType is MPSCNNReductionTypeMean, the accumulated loss value is divided by width * height instead of width * height * featureChannels.

Sigmoid Cross Entropy loss filter. This loss filter is applied element-wise. This loss function is computed according to the following formulas: Compute losses: losses = max(y, 0) - y * t + log(1 + exp(-|y|)) Compute weighted losses: weighted_losses = weight(s) * losses Compute overall loss: loss = reduce(weighted_losses, reductionType)

Categorical Cross Entropy loss filter. This loss filter is applied element-wise. This loss function is computed according to the following formulas: Compute losses: losses = -t * log(y) Compute weighted losses: weighted_losses = weight(s) * losses Compute overall loss: loss = reduce(weighted_losses, reductionType)

Hinge loss filter. This loss filter is applied element-wise. The labels are expected to be 0.0 or 1.0. This loss function is computed according to the following formulas: Compute losses: losses = max(1 - (t * y), 0.0f) Compute weighted losses: weighted_losses = weight(s) * losses Compute overall loss: loss = reduce(weighted_losses, reductionType)

Huber loss filter. This loss filter is applied element-wise. This loss function is computed according to the following formulas: Compute losses: if (|y - t| < = delta, losses = 0.5 * y^2 if (|y - t| > delta, losses = 0.5 * delta^2 + delta * (|y - t| - delta) Compute weighted losses: weighted_losses = weight(s) * losses Compute overall loss: loss = reduce(weighted_losses, reductionType)

Cosine Distance loss filter. This loss filter is applied element-wise. The only valid reduction type for this loss filter is MPSCNNReductionTypeSum. This loss function is computed according to the following formulas: Compute losses: loss = 1 - reduce_sum(y * t) Compute overall loss: weighted_loss = weight * loss

Log loss filter. This loss filter is applied element-wise. This loss function is computed according to the following formulas: Compute losses: losses = -(t * log(y + epsilon)) - ((1 - t) * log(1 - y + epsilon)) Compute weighted losses: weighted_losses = weight(s) * losses Compute overall loss: loss = reduce(weighted_losses, reductionType)

Kullback-Leibler Divergence loss filter. This loss filter is applied element-wise. The input (predictions) is expected to contain log-probabilities. This loss function is computed according to the following formulas: Compute losses: losses = t * (log(t) - y) Compute weighted losses: weighted_losses = weight(s) * losses Compute overall loss: loss = reduce(weighted_losses, reductionType)

For predictions (y) and labels (t), the loss gradient for each available loss filter type is computed as follows:

Mean Absolute Error loss. The loss gradient is computed according to the following formulas: Compute gradient: d/dy = (y - t) / |y - t| Compute weighted gradient: weighted_gradient = weight(s) * gradient

Mean Squared Error loss. The loss gradient is computed according to the following formulas: Compute gradient: d/dy = 2 * (y - t) Compute weighted gradient: weighted_gradient = weight(s) * gradient

SoftMax Cross Entropy loss. The loss gradient is computed according to the following formulas: First, apply the same label smoothing as in the MPSCNNLoss filter. Compute gradient: d/dy = y - t Compute weighted gradient: weighted_gradient = weight(s) * gradient

Sigmoid Cross Entropy loss. The loss gradient is computed according to the following formulas: First, apply the same label smoothing as in the MPSCNNLoss filter. Compute gradient: d/dy = (1 / (1 + exp(-y)) - t Compute weighted gradient: weighted_gradient = weight(s) * gradient

Categorical Cross Entropy loss. The loss gradient is computed according to the following formulas: Compute gradient: d/dy = -t / y Compute weighted gradient: weighted_gradient = weight(s) * gradient

Hinge loss. The loss gradient is computed according to the following formulas: Compute gradient: d/dy = ((1 + ((1 - (2 * t)) * y)) > 0) ? 1 - (2 * t) : 0 Compute weighted gradient: weighted_gradient = weight(s) * gradient

Huber loss. The loss gradient is computed according to the following formulas: Compute gradient: d/dy = |y - t| > delta ? delta : y - t Compute weighted gradient: weighted_gradient = weight(s) * gradient

Cosine Distance loss. The loss gradient is computed according to the following formulas: Compute gradient: d/dy = -t Compute weighted gradient: weighted_gradient = weight(s) * gradient

Log loss. The loss gradient is computed according to the following formulas: Compute gradient: d/dy = (-2 * epsilon * t - t + y + epsilon) / (y * (1 - y) + epsilon * (epsilon + 1)) Compute weighted gradient: weighted_gradient = weight(s) * gradient

Kullback-Leibler Divergence loss. The loss gradient is computed according to the following formulas: Compute gradient: d/dy = -t / y Compute weighted gradient: weighted_gradient = weight(s) * gradient

The number of output feature channels remains the same as the number of input feature channels.

See also Apple’s documentation

Implementations

impl MPSCNNLoss

pub unsafe fn lossType(&self) -> MPSCNNLossType

Available on crate features MPSNeuralNetwork and MPSCNNTypes only.

See MPSCNNLossDescriptor for information about the following properties.

pub unsafe fn reductionType(&self) -> MPSCNNReductionType

Available on crate features MPSNeuralNetwork and MPSCNNTypes only.

pub unsafe fn weight(&self) -> c_float

Available on crate feature MPSNeuralNetwork only.

pub unsafe fn labelSmoothing(&self) -> c_float

Available on crate feature MPSNeuralNetwork only.

pub unsafe fn numberOfClasses(&self) -> NSUInteger

Available on crate feature MPSNeuralNetwork only.

pub unsafe fn epsilon(&self) -> c_float

Available on crate feature MPSNeuralNetwork only.

pub unsafe fn delta(&self) -> c_float

Available on crate feature MPSNeuralNetwork only.

pub unsafe fn reduceAcrossBatch(&self) -> bool

Available on crate feature MPSNeuralNetwork only.

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

Available on crate feature MPSNeuralNetwork only.

pub unsafe fn initWithDevice_lossDescriptor( this: Allocated<Self>, device: &ProtocolObject<dyn MTLDevice>, loss_descriptor: &MPSCNNLossDescriptor, ) -> Retained<Self>

Available on crate feature MPSNeuralNetwork only.

Initialize the loss filter with a loss descriptor.

Parameter device: The device the filter will run on.

Parameter lossDescriptor: The loss descriptor.

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

pub unsafe fn initWithCoder_device( this: Allocated<Self>, a_decoder: &NSCoder, device: &ProtocolObject<dyn MTLDevice>, ) -> Option<Retained<Self>>

Available on crate feature MPSNeuralNetwork only.

<NSSecureCoding

support

Safety

a_decoder possibly has further requirements.

pub unsafe fn encodeToCommandBuffer_sourceImage_labels_destinationImage( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, source_image: &MPSImage, labels: &MPSCNNLossLabels, destination_image: &MPSImage, )

Available on crate features MPSNeuralNetwork and MPSImage and MPSState only.

Encode a MPSCNNLoss filter and return a gradient in the destinationImage.

This filter consumes the output of a previous layer, for example, the SoftMax layer containing predictions, and the MPSCNNLossLabels object containing the target data (labels) and optionally, weights for the labels. The destinationImage contains the computed gradient for the loss layer. It serves as a source gradient input image to the first gradient layer (in the backward direction), in our example, the SoftMax gradient layer.

Parameter commandBuffer: The MTLCommandBuffer on which to encode.

Parameter sourceImage: The source image from the previous filter in the graph (in the inference direction).

Parameter labels: The object containing the target data (labels) and optionally, weights for the labels.

Parameter destinationImage: The MPSImage into which to write the gradient result.

pub unsafe fn encodeToCommandBuffer_sourceImage_labels( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, source_image: &MPSImage, labels: &MPSCNNLossLabels, ) -> Retained<MPSImage>

Available on crate features MPSNeuralNetwork and MPSImage and MPSState only.

Encode a MPSCNNLoss filter and return a gradient.

This -encode call is similar to the encodeToCommandBuffer:sourceImage:labels:destinationImage: above, except that it creates and returns the MPSImage with the loss gradient result.

Parameter commandBuffer: The MTLCommandBuffer on which to encode.

Parameter sourceImage: The source image from the previous filter in the graph (in the inference direction).

Parameter labels: The object containing the target data (labels) and optionally, weights for the labels.

Returns: The MPSImage containing the gradient result.

pub unsafe fn encodeBatchToCommandBuffer_sourceImages_labels_destinationImages( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, source_image: &MPSImageBatch, labels: &MPSCNNLossLabelsBatch, destination_image: &MPSImageBatch, )

Available on crate features MPSNeuralNetwork and MPSImage and MPSNDArray and MPSState only.

pub unsafe fn encodeBatchToCommandBuffer_sourceImages_labels( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, source_image: &MPSImageBatch, labels: &MPSCNNLossLabelsBatch, ) -> Retained<MPSImageBatch>

Available on crate features MPSNeuralNetwork and MPSImage and MPSNDArray and MPSState only.

impl MPSCNNLoss

Methods declared on superclass MPSKernel.

pub unsafe fn initWithCoder( this: Allocated<Self>, a_decoder: &NSCoder, ) -> Option<Retained<Self>>

Available on crate feature MPSNeuralNetwork only.

Called by NSCoder to decode MPSKernels

This isn’t the right interface to decode a MPSKernel, but it is the one that NSCoder uses. To enable your NSCoder (e.g. NSKeyedUnarchiver) to set which device to use extend the object to adopt the MPSDeviceProvider protocol. Otherwise, the Metal system default device will be used.

Safety

a_decoder possibly has further requirements.

impl MPSCNNLoss

Methods declared on superclass NSObject.

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

Available on crate feature MPSNeuralNetwork only.

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

Available on crate feature MPSNeuralNetwork only.

Methods from Deref<Target = MPSCNNKernel>

pub unsafe fn offset(&self) -> MPSOffset

Available on crate features MPSNeuralNetwork and MPSCoreTypes only.

The position of the destination clip rectangle origin relative to the source buffer.

The offset is defined to be the position of clipRect.origin in source coordinates. Default: {0,0,0}, indicating that the top left corners of the clipRect and source image align. offset.z is the index of starting source image in batch processing mode.

See Also: MetalPerformanceShaders.hsubsubsection_mpsoffset

pub unsafe fn setOffset(&self, offset: MPSOffset)

Available on crate features MPSNeuralNetwork and MPSCoreTypes only.

Setter for offset.

pub unsafe fn clipRect(&self) -> MTLRegion

Available on crate feature MPSNeuralNetwork only.

An optional clip rectangle to use when writing data. Only the pixels in the rectangle will be overwritten.

A MTLRegion that indicates which part of the destination to overwrite. If the clipRect does not lie completely within the destination image, the intersection between clip rectangle and destination bounds is used. Default: MPSRectNoClip (MPSKernel::MPSRectNoClip) indicating the entire image. clipRect.origin.z is the index of starting destination image in batch processing mode. clipRect.size.depth is the number of images to process in batch processing mode.

See Also: MetalPerformanceShaders.hsubsubsection_clipRect

pub unsafe fn setClipRect(&self, clip_rect: MTLRegion)

Available on crate feature MPSNeuralNetwork only.

Setter for clipRect.

pub unsafe fn destinationFeatureChannelOffset(&self) -> NSUInteger

Available on crate feature MPSNeuralNetwork only.

The number of channels in the destination MPSImage to skip before writing output.

This is the starting offset into the destination image in the feature channel dimension at which destination data is written. This allows an application to pass a subset of all the channels in MPSImage as output of MPSKernel. E.g. Suppose MPSImage has 24 channels and a MPSKernel outputs 8 channels. If we want channels 8 to 15 of this MPSImage to be used as output, we can set destinationFeatureChannelOffset = 8. Note that this offset applies independently to each image when the MPSImage is a container for multiple images and the MPSCNNKernel is processing multiple images (clipRect.size.depth > 1). The default value is 0 and any value specifed shall be a multiple of 4. If MPSKernel outputs N channels, the destination image MUST have at least destinationFeatureChannelOffset + N channels. Using a destination image with insufficient number of feature channels will result in an error. E.g. if the MPSCNNConvolution outputs 32 channels, and the destination has 64 channels, then it is an error to set destinationFeatureChannelOffset > 32.

pub unsafe fn setDestinationFeatureChannelOffset( &self, destination_feature_channel_offset: NSUInteger, )

Available on crate feature MPSNeuralNetwork only.

Setter for destinationFeatureChannelOffset.

pub unsafe fn sourceFeatureChannelOffset(&self) -> NSUInteger

Available on crate feature MPSNeuralNetwork only.

The number of channels in the source MPSImage to skip before reading the input.

This is the starting offset into the source image in the feature channel dimension at which source data is read. Unit: feature channels This allows an application to read a subset of all the channels in MPSImage as input of MPSKernel. E.g. Suppose MPSImage has 24 channels and a MPSKernel needs to read 8 channels. If we want channels 8 to 15 of this MPSImage to be used as input, we can set sourceFeatureChannelOffset = 8. Note that this offset applies independently to each image when the MPSImage is a container for multiple images and the MPSCNNKernel is processing multiple images (clipRect.size.depth > 1). The default value is 0 and any value specifed shall be a multiple of 4. If MPSKernel inputs N channels, the source image MUST have at least sourceFeatureChannelOffset + N channels. Using a source image with insufficient number of feature channels will result in an error. E.g. if the MPSCNNConvolution inputs 32 channels, and the source has 64 channels, then it is an error to set sourceFeatureChannelOffset > 32.

pub unsafe fn setSourceFeatureChannelOffset( &self, source_feature_channel_offset: NSUInteger, )

Available on crate feature MPSNeuralNetwork only.

Setter for sourceFeatureChannelOffset.

pub unsafe fn sourceFeatureChannelMaxCount(&self) -> NSUInteger

Available on crate feature MPSNeuralNetwork only.

The maximum number of channels in the source MPSImage to use

Most filters can insert a slice operation into the filter for free. Use this to limit the size of the feature channel slice taken from the input image. If the value is too large, it is truncated to be the remaining size in the image after the sourceFeatureChannelOffset is taken into account. Default: ULONG_MAX

pub unsafe fn setSourceFeatureChannelMaxCount( &self, source_feature_channel_max_count: NSUInteger, )

Available on crate feature MPSNeuralNetwork only.

Setter for sourceFeatureChannelMaxCount.

pub unsafe fn edgeMode(&self) -> MPSImageEdgeMode

Available on crate features MPSNeuralNetwork and MPSCoreTypes only.

The MPSImageEdgeMode to use when texture reads stray off the edge of an image

Most MPSKernel objects can read off the edge of the source image. This can happen because of a negative offset property, because the offset + clipRect.size is larger than the source image or because the filter looks at neighboring pixels, such as a Convolution filter. Default: MPSImageEdgeModeZero.

See Also: MetalPerformanceShaders.hsubsubsection_edgemode Note: For MPSCNNPoolingAveragespecifying edge mode MPSImageEdgeModeClampis interpreted as a “shrink-to-edge” operation, which shrinks the effective filtering window to remain within the source image borders.

pub unsafe fn setEdgeMode(&self, edge_mode: MPSImageEdgeMode)

Available on crate features MPSNeuralNetwork and MPSCoreTypes only.

Setter for edgeMode.

pub unsafe fn kernelWidth(&self) -> NSUInteger

Available on crate feature MPSNeuralNetwork only.

The width of the MPSCNNKernel filter window

This is the horizontal diameter of the region read by the filter for each result pixel. If the MPSCNNKernel does not have a filter window, then 1 will be returned.

Warning: This property was lowered to this class in ios/tvos 11 The property may not be available on iOS/tvOS 10 for all subclasses of MPSCNNKernel

pub unsafe fn kernelHeight(&self) -> NSUInteger

Available on crate feature MPSNeuralNetwork only.

The height of the MPSCNNKernel filter window

This is the vertical diameter of the region read by the filter for each result pixel. If the MPSCNNKernel does not have a filter window, then 1 will be returned.

Warning: This property was lowered to this class in ios/tvos 11 The property may not be available on iOS/tvOS 10 for all subclasses of MPSCNNKernel

pub unsafe fn strideInPixelsX(&self) -> NSUInteger

Available on crate feature MPSNeuralNetwork only.

The downsampling (or upsampling if a backwards filter) factor in the horizontal dimension

If the filter does not do up or downsampling, 1 is returned.

Warning: This property was lowered to this class in ios/tvos 11 The property may not be available on iOS/tvOS 10 for all subclasses of MPSCNNKernel

pub unsafe fn strideInPixelsY(&self) -> NSUInteger

Available on crate feature MPSNeuralNetwork only.

The downsampling (or upsampling if a backwards filter) factor in the vertical dimension

If the filter does not do up or downsampling, 1 is returned.

Warning: This property was lowered to this class in ios/tvos 11 The property may not be available on iOS/tvOS 10 for all subclasses of MPSCNNKernel

pub unsafe fn dilationRateX(&self) -> NSUInteger

Available on crate feature MPSNeuralNetwork only.

Stride in source coordinates from one kernel tap to the next in the X dimension.

pub unsafe fn dilationRateY(&self) -> NSUInteger

Available on crate feature MPSNeuralNetwork only.

Stride in source coordinates from one kernel tap to the next in the Y dimension.

pub unsafe fn isBackwards(&self) -> bool

Available on crate feature MPSNeuralNetwork only.

YES if the filter operates backwards.

This influences how strideInPixelsX/Y should be interpreted. Most filters either have stride 1 or are reducing, meaning that the result image is smaller than the original by roughly a factor of the stride. A few “backward” filters (e.g convolution transpose) are intended to “undo” the effects of an earlier forward filter, and so enlarge the image. The stride is in the destination coordinate frame rather than the source coordinate frame.

pub unsafe fn isStateModified(&self) -> bool

Available on crate feature MPSNeuralNetwork only.

Returns true if the -encode call modifies the state object it accepts.

pub unsafe fn padding(&self) -> Retained<ProtocolObject<dyn MPSNNPadding>>

Available on crate features MPSNeuralNetwork and MPSNeuralNetworkTypes only.

The padding method used by the filter

This influences how the destination image is sized and how the offset into the source image is set. It is used by the -encode methods that return a MPSImage from the left hand side.

pub unsafe fn setPadding(&self, padding: &ProtocolObject<dyn MPSNNPadding>)

Available on crate features MPSNeuralNetwork and MPSNeuralNetworkTypes only.

Setter for padding.

pub unsafe fn destinationImageAllocator( &self, ) -> Retained<ProtocolObject<dyn MPSImageAllocator>>

Available on crate features MPSNeuralNetwork and MPSImage only.

Method to allocate the result image for -encodeToCommandBuffer:sourceImage:

Default: MPSTemporaryImage.defaultAllocator

pub unsafe fn setDestinationImageAllocator( &self, destination_image_allocator: &ProtocolObject<dyn MPSImageAllocator>, )

Available on crate features MPSNeuralNetwork and MPSImage only.

Setter for destinationImageAllocator.

pub unsafe fn encodeToCommandBuffer_sourceImage_destinationImage( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, source_image: &MPSImage, destination_image: &MPSImage, )

Available on crate features MPSNeuralNetwork and MPSImage only.

Encode a MPSCNNKernel into a command Buffer. The operation shall proceed out-of-place.

This is the older style of encode which reads the offset, doesn’t change it, and ignores the padding method.

Parameter commandBuffer: A valid MTLCommandBuffer to receive the encoded filter

Parameter sourceImage: A valid MPSImage object containing the source image.

Parameter destinationImage: A valid MPSImage to be overwritten by result image. destinationImage may not alias sourceImage.

pub unsafe fn encodeToCommandBuffer_sourceImage_destinationState_destinationImage( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, source_image: &MPSImage, destination_state: &MPSState, destination_image: &MPSImage, )

Available on crate features MPSNeuralNetwork and MPSImage and MPSState only.

Encode a MPSCNNKernel with a destination state into a command Buffer.

This is typically used during training. The state is commonly a MPSNNGradientState. Please see -resultStateForSourceImages:SourceStates: and batch+temporary variants.

Parameter commandBuffer: A valid MTLCommandBuffer to receive the encoded filter

Parameter sourceImage: A valid MPSImage object containing the source image.

Parameter destinationState: A state to be overwritten by additional state information.

Parameter destinationImage: A valid MPSImage to be overwritten by result image. destinationImage may not alias sourceImage.

pub unsafe fn encodeBatchToCommandBuffer_sourceImages_destinationImages( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, source_images: &MPSImageBatch, destination_images: &MPSImageBatch, )

Available on crate features MPSNeuralNetwork and MPSImage and MPSNDArray only.

Encode a MPSCNNKernel into a command Buffer. The operation shall proceed out-of-place.

This is the older style of encode which reads the offset, doesn’t change it, and ignores the padding method.

Parameter commandBuffer: A valid MTLCommandBuffer to receive the encoded filter

Parameter sourceImages: A valid MPSImage object containing the source images.

Parameter destinationImages: A valid MPSImage to be overwritten by result images. destinationImages may not alias sourceImages, even at different indices.

pub unsafe fn encodeBatchToCommandBuffer_sourceImages_destinationStates_destinationImages( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, source_images: &MPSImageBatch, destination_states: Option<&MPSStateBatch>, destination_images: &MPSImageBatch, )

Available on crate features MPSNeuralNetwork and MPSImage and MPSNDArray and MPSState only.

Encode a MPSCNNKernel with a destination state into a command Buffer.

This is typically used during training. The state is commonly a MPSNNGradientState. Please see -resultStateForSourceImages:SourceStates:destinationImage and batch+temporary variants.

Parameter commandBuffer: A valid MTLCommandBuffer to receive the encoded filter

Parameter sourceImages: A valid MPSImage object containing the source images.

Parameter destinationStates: A list of states to be overwritten by results

Parameter destinationImages: A valid MPSImage to be overwritten by result images. destinationImages may not alias sourceImages, even at different indices.

pub unsafe fn encodeToCommandBuffer_sourceImage( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, source_image: &MPSImage, ) -> Retained<MPSImage>

Available on crate features MPSNeuralNetwork and MPSImage only.

Encode a MPSCNNKernel into a command Buffer. Create a texture to hold the result and return it.

In the first iteration on this method, encodeToCommandBuffer:sourceImage:destinationImage: some work was left for the developer to do in the form of correctly setting the offset property and sizing the result buffer. With the introduction of the padding policy (see padding property) the filter can do this work itself. If you would like to have some input into what sort of MPSImage (e.g. temporary vs. regular) or what size it is or where it is allocated, you may set the destinationImageAllocator to allocate the image yourself.

This method uses the MPSNNPadding padding property to figure out how to size the result image and to set the offset property. See discussion in MPSNeuralNetworkTypes.h. All images in a batch must have MPSImage.numberOfImages = 1.

Parameter commandBuffer: The command buffer

Parameter sourceImage: A MPSImage to use as the source images for the filter.

Returns: A MPSImage or MPSTemporaryImage allocated per the destinationImageAllocator containing the output of the graph. The offset property will be adjusted to reflect the offset used during the encode. The returned image will be automatically released when the command buffer completes. If you want to keep it around for longer, retain the image. (ARC will do this for you if you use it later.)

pub unsafe fn encodeToCommandBuffer_sourceImage_destinationState_destinationStateIsTemporary( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, source_image: &MPSImage, out_state: &mut Option<Retained<MPSState>>, is_temporary: bool, ) -> Retained<MPSImage>

Available on crate features MPSNeuralNetwork and MPSImage and MPSState only.

Encode a MPSCNNKernel into a command Buffer. Create a texture and state to hold the results and return them.

In the first iteration on this method, encodeToCommandBuffer:sourceImage:destinationState:destinationImage: some work was left for the developer to do in the form of correctly setting the offset property and sizing the result buffer. With the introduction of the padding policy (see padding property) the filter can do this work itself. If you would like to have some input into what sort of MPSImage (e.g. temporary vs. regular) or what size it is or where it is allocated, you may set the destinationImageAllocator to allocate the image yourself.

This method uses the MPSNNPadding padding property to figure out how to size the result image and to set the offset property. See discussion in MPSNeuralNetworkTypes.h. All images in a batch must have MPSImage.numberOfImages = 1.

Parameter commandBuffer: The command buffer

Parameter sourceImage: A MPSImage to use as the source images for the filter.

Parameter outState: A new state object is returned here.

Returns: A MPSImage or MPSTemporaryImage allocated per the destinationImageAllocator containing the output of the graph. The offset property will be adjusted to reflect the offset used during the encode. The returned image will be automatically released when the command buffer completes. If you want to keep it around for longer, retain the image. (ARC will do this for you if you use it later.)

pub unsafe fn encodeBatchToCommandBuffer_sourceImages( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, source_images: &MPSImageBatch, ) -> Retained<MPSImageBatch>

Available on crate features MPSNeuralNetwork and MPSImage and MPSNDArray only.

Encode a MPSCNNKernel into a command Buffer. Create a texture to hold the result and return it.

In the first iteration on this method, encodeToCommandBuffer:sourceImage:destinationImage: some work was left for the developer to do in the form of correctly setting the offset property and sizing the result buffer. With the introduction of the padding policy (see padding property) the filter can do this work itself. If you would like to have some input into what sort of MPSImage (e.g. temporary vs. regular) or what size it is or where it is allocated, you may set the destinationImageAllocator to allocate the image yourself.

This method uses the MPSNNPadding padding property to figure out how to size the result image and to set the offset property. See discussion in MPSNeuralNetworkTypes.h. All images in a batch must have MPSImage.numberOfImages = 1.

Parameter commandBuffer: The command buffer

Parameter sourceImages: A MPSImages to use as the source images for the filter.

Returns: An array of MPSImages or MPSTemporaryImages allocated per the destinationImageAllocator containing the output of the graph. The offset property will be adjusted to reflect the offset used during the encode. The returned images will be automatically released when the command buffer completes. If you want to keep them around for longer, retain the images.

pub unsafe fn encodeBatchToCommandBuffer_sourceImages_destinationStates_destinationStateIsTemporary( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, source_images: &MPSImageBatch, out_states: &mut Option<Retained<MPSStateBatch>>, is_temporary: bool, ) -> Retained<MPSImageBatch>

Available on crate features MPSNeuralNetwork and MPSImage and MPSNDArray and MPSState only.

Encode a MPSCNNKernel into a command Buffer. Create a MPSImageBatch and MPSStateBatch to hold the results and return them.

In the first iteration on this method, encodeToCommandBuffer:sourceImage:destinationImage: some work was left for the developer to do in the form of correctly setting the offset property and sizing the result buffer. With the introduction of the padding policy (see padding property) the filter can do this work itself. If you would like to have some input into what sort of MPSImage (e.g. temporary vs. regular) or what size it is or where it is allocated, you may set the destinationImageAllocator to allocate the image yourself.

This method uses the MPSNNPadding padding property to figure out how to size the result image and to set the offset property. See discussion in MPSNeuralNetworkTypes.h. All images in a batch must have MPSImage.numberOfImages = 1.

Usage:

                  MPSStateBatch * outStates = nil;    // autoreleased
                  MPSImageBatch * result = [k encodeBatchToCommandBuffer: cmdBuf
                                                            sourceImages: sourceImages
                                                       destinationStates: &outStates ];

Parameter commandBuffer: The command buffer

Parameter sourceImages: A MPSImages to use as the source images for the filter.

Parameter outStates: A pointer to storage to hold a MPSStateBatch* where output states are returned

Returns: An array of MPSImages or MPSTemporaryImages allocated per the destinationImageAllocator containing the output of the graph. The offset property will be adjusted to reflect the offset used during the encode. The returned images will be automatically released when the command buffer completes. If you want to keep them around for longer, retain the images.

pub unsafe fn resultStateForSourceImage_sourceStates_destinationImage( &self, source_image: &MPSImage, source_states: Option<&NSArray<MPSState>>, destination_image: &MPSImage, ) -> Option<Retained<MPSState>>

Available on crate features MPSNeuralNetwork and MPSImage and MPSState only.

Allocate a MPSState (subclass) to hold the results from a -encodeBatchToCommandBuffer… operation

A graph may need to allocate storage up front before executing. This may be necessary to avoid using too much memory and to manage large batches. The function should allocate any MPSState objects that will be produced by an -encode call with the indicated sourceImages and sourceStates inputs. Though the states can be further adjusted in the ensuing -encode call, the states should be initialized with all important data and all MTLResource storage allocated. The data stored in the MTLResource need not be initialized, unless the ensuing -encode call expects it to be.

The MTLDevice used by the result is derived from the source image. The padding policy will be applied to the filter before this is called to give it the chance to configure any properties like MPSCNNKernel.offset.

CAUTION: The kernel must have all properties set to values that will ultimately be passed to the -encode call that writes to the state, before -resultStateForSourceImages:sourceStates:destinationImage: is called or behavior is undefined. Please note that -destinationImageDescriptorForSourceImages:sourceStates: will alter some of these properties automatically based on the padding policy. If you intend to call that to make the destination image, then you should call that before -resultStateForSourceImages:sourceStates:destinationImage:. This will ensure the properties used in the encode call and in the destination image creation match those used to configure the state.

The following order is recommended:

// Configure MPSCNNKernel properties first kernel.edgeMode = MPSImageEdgeModeZero; kernel.destinationFeatureChannelOffset = 128; // concatenation without the copy …

// ALERT: will change MPSCNNKernel properties MPSImageDescriptor * d = [kernel destinationImageDescriptorForSourceImage: source sourceStates: states]; MPSTemporaryImage * dest = [MPSTemporaryImage temporaryImageWithCommandBuffer: cmdBuf imageDescriptor: d];

// Now that all properties are configured properly, we can make the result state // and call encode. MPSState * __nullable destState = [kernel resultStateForSourceImage: source sourceStates: states destinationImage: dest];

// This form of -encode will be declared by the MPSCNNKernel subclass [kernel encodeToCommandBuffer: cmdBuf sourceImage: source destinationState: destState destinationImage: dest ];

Default: returns nil

Parameter sourceImage: The MPSImage consumed by the associated -encode call.

Parameter sourceStates: The list of MPSStates consumed by the associated -encode call, for a batch size of 1.

Parameter destinationImage: The destination image for the encode call

Returns: The list of states produced by the -encode call for batch size of 1. When the batch size is not 1, this function will be called repeatedly unless -isResultStateReusedAcrossBatch returns YES. If -isResultStateReusedAcrossBatch returns YES, then it will be called once per batch and the MPSStateBatch array will contain MPSStateBatch.length references to the same object.

pub unsafe fn resultStateBatchForSourceImage_sourceStates_destinationImage( &self, source_image: &MPSImageBatch, source_states: Option<&NSArray<MPSStateBatch>>, destination_image: &MPSImageBatch, ) -> Option<Retained<MPSStateBatch>>

Available on crate features MPSNeuralNetwork and MPSImage and MPSNDArray and MPSState only.

pub unsafe fn temporaryResultStateForCommandBuffer_sourceImage_sourceStates_destinationImage( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, source_image: &MPSImage, source_states: Option<&NSArray<MPSState>>, destination_image: &MPSImage, ) -> Option<Retained<MPSState>>

Available on crate features MPSNeuralNetwork and MPSImage and MPSState only.

Allocate a temporary MPSState (subclass) to hold the results from a -encodeBatchToCommandBuffer… operation

A graph may need to allocate storage up front before executing. This may be necessary to avoid using too much memory and to manage large batches. The function should allocate any MPSState objects that will be produced by an -encode call with the indicated sourceImages and sourceStates inputs. Though the states can be further adjusted in the ensuing -encode call, the states should be initialized with all important data and all MTLResource storage allocated. The data stored in the MTLResource need not be initialized, unless the ensuing -encode call expects it to be.

The MTLDevice used by the result is derived from the command buffer. The padding policy will be applied to the filter before this is called to give it the chance to configure any properties like MPSCNNKernel.offset.

CAUTION: The kernel must have all properties set to values that will ultimately be passed to the -encode call that writes to the state, before -resultStateForSourceImages:sourceStates:destinationImage: is called or behavior is undefined. Please note that -destinationImageDescriptorForSourceImages:sourceStates:destinationImage: will alter some of these properties automatically based on the padding policy. If you intend to call that to make the destination image, then you should call that before -resultStateForSourceImages:sourceStates:destinationImage:. This will ensure the properties used in the encode call and in the destination image creation match those used to configure the state.

The following order is recommended:

// Configure MPSCNNKernel properties first kernel.edgeMode = MPSImageEdgeModeZero; kernel.destinationFeatureChannelOffset = 128; // concatenation without the copy …

// ALERT: will change MPSCNNKernel properties MPSImageDescriptor * d = [kernel destinationImageDescriptorForSourceImage: source sourceStates: states]; MPSTemporaryImage * dest = [MPSTemporaryImage temporaryImageWithCommandBuffer: cmdBuf imageDescriptor: d];

// Now that all properties are configured properly, we can make the result state // and call encode. MPSState * __nullable destState = [kernel temporaryResultStateForCommandBuffer: cmdBuf sourceImage: source sourceStates: states];

// This form of -encode will be declared by the MPSCNNKernel subclass [kernel encodeToCommandBuffer: cmdBuf sourceImage: source destinationState: destState destinationImage: dest ];

Default: returns nil

Parameter commandBuffer: The command buffer to allocate the temporary storage against The state will only be valid on this command buffer.

Parameter sourceImage: The MPSImage consumed by the associated -encode call.

Parameter sourceStates: The list of MPSStates consumed by the associated -encode call, for a batch size of 1.

Parameter destinationImage: The destination image for the encode call

Returns: The list of states produced by the -encode call for batch size of 1. When the batch size is not 1, this function will be called repeatedly unless -isResultStateReusedAcrossBatch returns YES. If -isResultStateReusedAcrossBatch returns YES, then it will be called once per batch and the MPSStateBatch array will contain MPSStateBatch.length references to the same object.

pub unsafe fn temporaryResultStateBatchForCommandBuffer_sourceImage_sourceStates_destinationImage( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, source_image: &MPSImageBatch, source_states: Option<&NSArray<MPSStateBatch>>, destination_image: &MPSImageBatch, ) -> Option<Retained<MPSStateBatch>>

Available on crate features MPSNeuralNetwork and MPSImage and MPSNDArray and MPSState only.

pub unsafe fn isResultStateReusedAcrossBatch(&self) -> bool

Available on crate feature MPSNeuralNetwork only.

Returns YES if the same state is used for every operation in a batch

If NO, then each image in a MPSImageBatch will need a corresponding (and different) state to go with it. Set to YES to avoid allocating redundant state in the case when the same state is used all the time. Default: NO

pub unsafe fn appendBatchBarrier(&self) -> bool

Available on crate feature MPSNeuralNetwork only.

Returns YES if the filter must be run over the entire batch before its results may be used

Nearly all filters do not need to see the entire batch all at once and can operate correctly with partial batches. This allows the graph to strip-mine the problem, processing the graph top to bottom on a subset of the batch at a time, dramatically reducing memory usage. As the full nominal working set for a graph is often so large that it may not fit in memory, sub-batching may be required forward progress.

Batch normalization statistics on the other hand must complete the batch before the statistics may be used to normalize the images in the batch in the ensuing normalization filter. Consequently, batch normalization statistics requests the graph insert a batch barrier following it by returning YES from -appendBatchBarrier. This tells the graph to complete the batch before any dependent filters can start. Note that the filter itself may still be subject to sub-batching in its operation. All filters must be able to function without seeing the entire batch in a single -encode call. Carry over state that is accumulated across sub-batches is commonly carried in a shared MPSState containing a MTLBuffer. See -isResultStateReusedAcrossBatch.

Caution: on most supported devices, the working set may be so large that the graph may be forced to throw away and recalculate most intermediate images in cases where strip-mining can not occur because -appendBatchBarrier returns YES. A single batch barrier can commonly cause a memory size increase and/or performance reduction by many fold over the entire graph. Filters of this variety should be avoided.

Default: NO

pub unsafe fn destinationImageDescriptorForSourceImages_sourceStates( &self, source_images: &NSArray<MPSImage>, source_states: Option<&NSArray<MPSState>>, ) -> Retained<MPSImageDescriptor>

Available on crate features MPSNeuralNetwork and MPSImage and MPSState only.

Get a suggested destination image descriptor for a source image

Your application is certainly free to pass in any destinationImage it likes to encodeToCommandBuffer:sourceImage:destinationImage, within reason. This is the basic design for iOS 10. This method is therefore not required.

However, calculating the MPSImage size and MPSCNNKernel properties for each filter can be tedious and complicated work, so this method is made available to automate the process. The application may modify the properties of the descriptor before a MPSImage is made from it, so long as the choice is sensible for the kernel in question. Please see individual kernel descriptions for restrictions.

The expected timeline for use is as follows:

1. This method is called: a) The default MPS padding calculation is applied. It uses the MPSNNPaddingMethod of the .padding property to provide a consistent addressing scheme over the graph. It creates the MPSImageDescriptor and adjusts the .offset property of the MPSNNKernel. When using a MPSNNGraph, the padding is set using the MPSNNFilterNode as a proxy.

b) This method may be overridden by MPSCNNKernel subclass to achieve any customization appropriate to the object type.

c) Source states are then applied in order. These may modify the descriptor and may update other object properties. See: -destinationImageDescriptorForSourceImages:sourceStates: forKernel:suggestedDescriptor: This is the typical way in which MPS may attempt to influence the operation of its kernels.

d) If the .padding property has a custom padding policy method of the same name, it is called. Similarly, it may also adjust the descriptor and any MPSCNNKernel properties. This is the typical way in which your application may attempt to influence the operation of the MPS kernels.

2. A result is returned from this method and the caller may further adjust the descriptor and kernel properties directly.

3. The caller uses the descriptor to make a new MPSImage to use as the destination image for the -encode call in step 5.

4. The caller calls -resultStateForSourceImage:sourceStates:destinationImage: to make any result states needed for the kernel. If there isn’t one, it will return nil. A variant is available to return a temporary state instead.

5. a -encode method is called to encode the kernel.

The entire process 1-5 is more simply achieved by just calling an -encode… method that returns a MPSImage out the left hand sid of the method. Simpler still, use the MPSNNGraph to coordinate the entire process from end to end. Opportunities to influence the process are of course reduced, as (2) is no longer possible with either method. Your application may opt to use the five step method if it requires greater customization as described, or if it would like to estimate storage in advance based on the sum of MPSImageDescriptors before processing a graph. Storage estimation is done by using the MPSImageDescriptor to create a MPSImage (without passing it a texture), and then call -resourceSize. As long as the MPSImage is not used in an encode call and the .texture property is not invoked, the underlying MTLTexture is not created.

No destination state or destination image is provided as an argument to this function because it is expected they will be made / configured after this is called. This method is expected to auto-configure important object properties that may be needed in the ensuing destination image and state creation steps.

Parameter sourceImages: A array of source images that will be passed into the -encode call Since MPSCNNKernel is a unary kernel, it is an array of length 1.

Parameter sourceStates: An optional array of source states that will be passed into the -encode call

Returns: an image descriptor allocated on the autorelease pool

pub unsafe fn encodingStorageSizeForSourceImage_sourceStates_destinationImage( &self, source_image: &MPSImage, source_states: Option<&NSArray<MPSState>>, destination_image: Option<&MPSImage>, ) -> NSUInteger

Available on crate features MPSNeuralNetwork and MPSImage and MPSState only.

The size of extra MPS heap storage allocated while the kernel is encoding

This is best effort and just describes things that are likely to end up on the MPS heap. It does not describe all allocation done by the -encode call. It is intended for use with high water calculations for MTLHeap sizing. Allocations are typically for temporary storage needed for multipass algorithms. This interface should not be used to detect multipass algorithms.

pub unsafe fn batchEncodingStorageSizeForSourceImage_sourceStates_destinationImage( &self, source_image: &MPSImageBatch, source_states: Option<&NSArray<MPSStateBatch>>, destination_image: Option<&MPSImageBatch>, ) -> NSUInteger

Available on crate features MPSNeuralNetwork and MPSImage and MPSNDArray and MPSState only.

The size of extra MPS heap storage allocated while the kernel is encoding a batch

This is best effort and just describes things that are likely to end up on the MPS heap. It does not describe all allocation done by the -encode call. It is intended for use with high water calculations for MTLHeap sizing. Allocations are typically for temporary storage needed for multipass algorithms. This interface should not be used to detect multipass algorithms.

Methods from Deref<Target = MPSKernel>

pub unsafe fn options(&self) -> MPSKernelOptions

Available on crate feature MPSCoreTypes only.

The set of options used to run the kernel. subsubsection_options

pub unsafe fn setOptions(&self, options: MPSKernelOptions)

Available on crate feature MPSCoreTypes only.

Setter for options.

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

The device on which the kernel will be used

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

A string to help identify this object.

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

Setter for label.

This is copied when set.

pub unsafe fn copyWithZone_device( &self, zone: *mut NSZone, device: Option<&ProtocolObject<dyn MTLDevice>>, ) -> Retained<Self>

Make a copy of this MPSKernel for a new device

-copyWithZone: will call this API to make a copy of the MPSKernel on the same device. This interface may also be called directly to make a copy of the MPSKernel on a new device. Typically, the same MPSKernels should not be used to encode kernels on multiple command buffers from multiple threads. Many MPSKernels have mutable properties that might be changed by the other thread while this one is trying to encode. If you need to use a MPSKernel from multiple threads make a copy of it for each additional thread using -copyWithZone: or -copyWithZone:device:

Parameter zone: The NSZone in which to allocate the object

Parameter device: The device for the new MPSKernel. If nil, then use self.device.

Returns: a pointer to a copy of this MPSKernel. This will fail, returning nil if the device is not supported. Devices must be MTLFeatureSet_iOS_GPUFamily2_v1 or later.

Safety

zone must be a valid pointer or null.

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 MPSCNNLoss

Available on crate feature MPSNeuralNetwork only.

fn as_ref(&self) -> &AnyObject

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

impl AsRef<MPSCNNKernel> for MPSCNNLoss

Available on crate feature MPSNeuralNetwork only.

fn as_ref(&self) -> &MPSCNNKernel

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

impl AsRef<MPSCNNLoss> for MPSCNNLoss

Available on crate feature MPSNeuralNetwork only.

fn as_ref(&self) -> &Self

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

impl AsRef<MPSKernel> for MPSCNNLoss

Available on crate feature MPSNeuralNetwork only.

fn as_ref(&self) -> &MPSKernel

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

impl AsRef<NSObject> for MPSCNNLoss

Available on crate feature MPSNeuralNetwork only.

fn as_ref(&self) -> &NSObject

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

impl Borrow<AnyObject> for MPSCNNLoss

Available on crate feature MPSNeuralNetwork only.

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<MPSCNNKernel> for MPSCNNLoss

Available on crate feature MPSNeuralNetwork only.

fn borrow(&self) -> &MPSCNNKernel

Immutably borrows from an owned value.

impl Borrow<MPSKernel> for MPSCNNLoss

Available on crate feature MPSNeuralNetwork only.

fn borrow(&self) -> &MPSKernel

Immutably borrows from an owned value.

impl Borrow<NSObject> for MPSCNNLoss

Available on crate feature MPSNeuralNetwork only.

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for MPSCNNLoss

Available on crate feature MPSNeuralNetwork only.

const NAME: &'static str = "MPSCNNLoss"

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

type Super = MPSCNNKernel

The superclass of this class.

type ThreadKind = <<MPSCNNLoss 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 CopyingHelper for MPSCNNLoss

Available on crate feature MPSNeuralNetwork only.

type Result = MPSCNNLoss

The immutable counterpart of the type, or Self if the type has no immutable counterpart.

impl Debug for MPSCNNLoss

Available on crate feature MPSNeuralNetwork only.

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

Formats the value using the given formatter.

impl Deref for MPSCNNLoss

Available on crate feature MPSNeuralNetwork only.

type Target = MPSCNNKernel

The resulting type after dereferencing.

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

Dereferences the value.

impl Hash for MPSCNNLoss

Available on crate feature MPSNeuralNetwork 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 MPSCNNLoss

Available on crate feature MPSNeuralNetwork only.

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

where Self: Sized,

Increment the reference count of the receiver.

impl NSCoding for MPSCNNLoss

Available on crate feature MPSNeuralNetwork only.

unsafe fn encodeWithCoder(&self, coder: &NSCoder)

where Self: Sized + Message,

Safety

unsafe fn initWithCoder( this: Allocated<Self>, coder: &NSCoder, ) -> Option<Retained<Self>>

where Self: Sized + Message,

Safety

impl NSCopying for MPSCNNLoss

Available on crate feature MPSNeuralNetwork only.

fn copy(&self) -> Retained<Self::Result>

where Self: Sized + Message + CopyingHelper,

Returns a new instance that’s a copy of the receiver.

unsafe fn copyWithZone(&self, zone: *mut NSZone) -> Retained<Self::Result>

where Self: Sized + Message + CopyingHelper,

Returns a new instance that’s a copy of the receiver.

impl NSObjectProtocol for MPSCNNLoss

Available on crate feature MPSNeuralNetwork 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 NSSecureCoding for MPSCNNLoss

Available on crate feature MPSNeuralNetwork only.

fn supportsSecureCoding() -> bool

where Self: Sized + ClassType,

impl PartialEq for MPSCNNLoss

Available on crate feature MPSNeuralNetwork 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 MPSCNNLoss

Available on crate feature MPSNeuralNetwork only.

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

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

impl DowncastTarget for MPSCNNLoss

Available on crate feature MPSNeuralNetwork only.

impl Eq for MPSCNNLoss

Available on crate feature MPSNeuralNetwork only.