pub struct MPSImageSubtract { /* private fields */ }MPSCore and MPSImage and MPSImageKernel and MPSImageMath and MPSKernel only.Expand description
Dependencies: This depends on Metal.framework.
Specifies the subtraction operator. For each pixel in the primary source image (x) and each pixel in a secondary source image (y), it applies the following function: result = ((primaryScale * x) - (secondaryScale * y)) + bias.
See also Apple’s documentation
Implementations§
Source§impl MPSImageSubtract
impl MPSImageSubtract
Sourcepub unsafe fn initWithDevice(
this: Allocated<Self>,
device: &ProtocolObject<dyn MTLDevice>,
) -> Retained<Self>
pub unsafe fn initWithDevice( this: Allocated<Self>, device: &ProtocolObject<dyn MTLDevice>, ) -> Retained<Self>
Initialize the subtraction operator
Parameter device: The device the filter will run on.
Returns: A valid MPSImageSubtract object or nil, if failure.
Source§impl MPSImageSubtract
Methods declared on superclass MPSBinaryImageKernel.
impl MPSImageSubtract
Methods declared on superclass MPSBinaryImageKernel.
Sourcepub unsafe fn initWithCoder_device(
this: Allocated<Self>,
a_decoder: &NSCoder,
device: &ProtocolObject<dyn MTLDevice>,
) -> Option<Retained<Self>>
pub unsafe fn initWithCoder_device( this: Allocated<Self>, a_decoder: &NSCoder, device: &ProtocolObject<dyn MTLDevice>, ) -> Option<Retained<Self>>
NSSecureCoding compatability
While the standard NSSecureCoding/NSCoding method -initWithCoder: should work, since the file can’t know which device your data is allocated on, we have to guess and may guess incorrectly. To avoid that problem, use initWithCoder:device instead.
Parameter aDecoder: The NSCoder subclass with your serialized MPSKernel
Parameter device: The MTLDevice on which to make the MPSKernel
Returns: A new MPSKernel object, or nil if failure.
§Safety
a_decoder possibly has further requirements.
Source§impl MPSImageSubtract
Methods declared on superclass MPSKernel.
impl MPSImageSubtract
Methods declared on superclass MPSKernel.
Sourcepub unsafe fn initWithCoder(
this: Allocated<Self>,
a_decoder: &NSCoder,
) -> Option<Retained<Self>>
pub unsafe fn initWithCoder( this: Allocated<Self>, a_decoder: &NSCoder, ) -> Option<Retained<Self>>
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.
Methods from Deref<Target = MPSImageArithmetic>§
pub unsafe fn primaryScale(&self) -> c_float
Sourcepub unsafe fn setPrimaryScale(&self, primary_scale: c_float)
pub unsafe fn setPrimaryScale(&self, primary_scale: c_float)
Setter for primaryScale.
pub unsafe fn secondaryScale(&self) -> c_float
Sourcepub unsafe fn setSecondaryScale(&self, secondary_scale: c_float)
pub unsafe fn setSecondaryScale(&self, secondary_scale: c_float)
Setter for secondaryScale.
pub unsafe fn bias(&self) -> c_float
Sourcepub unsafe fn primaryStrideInPixels(&self) -> MTLSize
pub unsafe fn primaryStrideInPixels(&self) -> MTLSize
The secondarySource stride in the x, y, and z dimensions. The only supported values are 0 or 1. The default value for each dimension is 1.
Sourcepub unsafe fn setPrimaryStrideInPixels(&self, primary_stride_in_pixels: MTLSize)
pub unsafe fn setPrimaryStrideInPixels(&self, primary_stride_in_pixels: MTLSize)
Setter for primaryStrideInPixels.
Sourcepub unsafe fn secondaryStrideInPixels(&self) -> MTLSize
pub unsafe fn secondaryStrideInPixels(&self) -> MTLSize
The secondarySource stride in the x, y, and z dimensions. The only supported values are 0 or 1. The default value for each dimension is 1.
Sourcepub unsafe fn setSecondaryStrideInPixels(
&self,
secondary_stride_in_pixels: MTLSize,
)
pub unsafe fn setSecondaryStrideInPixels( &self, secondary_stride_in_pixels: MTLSize, )
Setter for secondaryStrideInPixels.
Sourcepub unsafe fn minimumValue(&self) -> c_float
pub unsafe fn minimumValue(&self) -> c_float
minimumValue is to clamp the result of an arithmetic operation: result = clamp(result, minimumValue, maximumValue). The default value of minimumValue is -FLT_MAX.
Sourcepub unsafe fn setMinimumValue(&self, minimum_value: c_float)
pub unsafe fn setMinimumValue(&self, minimum_value: c_float)
Setter for minimumValue.
Sourcepub unsafe fn maximumValue(&self) -> c_float
pub unsafe fn maximumValue(&self) -> c_float
maximumValue is used to clamp the result of an arithmetic operation: result = clamp(result, minimumValue, maximumValue). The default value of maximumValue is FLT_MAX.
Sourcepub unsafe fn setMaximumValue(&self, maximum_value: c_float)
pub unsafe fn setMaximumValue(&self, maximum_value: c_float)
Setter for maximumValue.
Methods from Deref<Target = MPSBinaryImageKernel>§
Sourcepub unsafe fn primaryOffset(&self) -> MPSOffset
Available on crate feature MPSCoreTypes only.
pub unsafe fn primaryOffset(&self) -> MPSOffset
MPSCoreTypes only.The position of the destination clip rectangle origin relative to the primary 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 primary source image align.
See Also: MetalPerformanceShaders.hsubsubsection_mpsoffset
Sourcepub unsafe fn setPrimaryOffset(&self, primary_offset: MPSOffset)
Available on crate feature MPSCoreTypes only.
pub unsafe fn setPrimaryOffset(&self, primary_offset: MPSOffset)
MPSCoreTypes only.Setter for primaryOffset.
Sourcepub unsafe fn secondaryOffset(&self) -> MPSOffset
Available on crate feature MPSCoreTypes only.
pub unsafe fn secondaryOffset(&self) -> MPSOffset
MPSCoreTypes only.The position of the destination clip rectangle origin relative to the secondary 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 secondary source image align.
See Also: MetalPerformanceShaders.hsubsubsection_mpsoffset
Sourcepub unsafe fn setSecondaryOffset(&self, secondary_offset: MPSOffset)
Available on crate feature MPSCoreTypes only.
pub unsafe fn setSecondaryOffset(&self, secondary_offset: MPSOffset)
MPSCoreTypes only.Setter for secondaryOffset.
Sourcepub unsafe fn primaryEdgeMode(&self) -> MPSImageEdgeMode
Available on crate feature MPSCoreTypes only.
pub unsafe fn primaryEdgeMode(&self) -> MPSImageEdgeMode
MPSCoreTypes only.The MPSImageEdgeMode to use when texture reads stray off the edge of the primary source image
Most MPSKernel objects can read off the edge of a 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 or morphology filter. Default: usually MPSImageEdgeModeZero. (Some MPSKernel types default to MPSImageEdgeModeClamp, because MPSImageEdgeModeZero is either not supported or would produce unexpected results.)
See Also: MetalPerformanceShaders.hsubsubsection_edgemode
Sourcepub unsafe fn setPrimaryEdgeMode(&self, primary_edge_mode: MPSImageEdgeMode)
Available on crate feature MPSCoreTypes only.
pub unsafe fn setPrimaryEdgeMode(&self, primary_edge_mode: MPSImageEdgeMode)
MPSCoreTypes only.Setter for primaryEdgeMode.
Sourcepub unsafe fn secondaryEdgeMode(&self) -> MPSImageEdgeMode
Available on crate feature MPSCoreTypes only.
pub unsafe fn secondaryEdgeMode(&self) -> MPSImageEdgeMode
MPSCoreTypes only.The MPSImageEdgeMode to use when texture reads stray off the edge of the secondary source image
Most MPSKernel objects can read off the edge of a 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 or morphology filter. Default: usually MPSImageEdgeModeZero. (Some MPSKernel types default to MPSImageEdgeModeClamp, because MPSImageEdgeModeZero is either not supported or would produce unexpected results.)
See Also: MetalPerformanceShaders.hsubsubsection_edgemode
Sourcepub unsafe fn setSecondaryEdgeMode(&self, secondary_edge_mode: MPSImageEdgeMode)
Available on crate feature MPSCoreTypes only.
pub unsafe fn setSecondaryEdgeMode(&self, secondary_edge_mode: MPSImageEdgeMode)
MPSCoreTypes only.Setter for secondaryEdgeMode.
Sourcepub unsafe fn clipRect(&self) -> MTLRegion
pub unsafe fn clipRect(&self) -> MTLRegion
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.
See Also: MetalPerformanceShaders.hsubsubsection_clipRect
Sourcepub unsafe fn setClipRect(&self, clip_rect: MTLRegion)
pub unsafe fn setClipRect(&self, clip_rect: MTLRegion)
Setter for clipRect.
Sourcepub unsafe fn encodeToCommandBuffer_primaryTexture_inPlaceSecondaryTexture_fallbackCopyAllocator(
&self,
command_buffer: &ProtocolObject<dyn MTLCommandBuffer>,
primary_texture: &ProtocolObject<dyn MTLTexture>,
in_place_secondary_texture: NonNull<NonNull<ProtocolObject<dyn MTLTexture>>>,
copy_allocator: MPSCopyAllocator,
) -> bool
Available on crate feature block2 only.
pub unsafe fn encodeToCommandBuffer_primaryTexture_inPlaceSecondaryTexture_fallbackCopyAllocator( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, primary_texture: &ProtocolObject<dyn MTLTexture>, in_place_secondary_texture: NonNull<NonNull<ProtocolObject<dyn MTLTexture>>>, copy_allocator: MPSCopyAllocator, ) -> bool
block2 only.This method attempts to apply the MPSKernel in place on a texture.
In-place operation means that the same texture is used both to hold the input image and the results. Operating in-place can be an excellent way to reduce resource utilization, and save time and energy. While simple Metal kernels can not operate in place because textures can not be readable and writable at the same time, some MPSKernels can operate in place because they use multi-pass algorithms. Whether a MPSKernel can operate in-place can depend on current hardware, operating system revision and the parameters and properties passed to it. You should never assume that a MPSKernel will continue to work in place, even if you have observed it doing so before.
If the operation succeeds in-place, YES is returned. If the in-place operation fails and no copyAllocator is provided, then NO is returned. In neither case is the pointer held at *texture modified.
Failure during in-place operation is common. You may find it simplifies your code to provide a copyAllocator. When an in-place filter fails, your copyAllocator will be invoked to create a new texture in which to write the results, allowing the filter to proceed reliably out-of-place. The original texture will be released, replaced with a pointer to the new texture and YES will be returned. If the allocator returns an invalid texture, it is released, *texture remains unmodified and NO is returned. Please see the MPSCopyAllocator definition for a sample allocator implementation.
Note: Image filters that look at neighboring pixel values may actually consume more memory when operating in place than out of place. Many such operations are tiled internally to save intermediate texture storage, but can not tile when operating in place. The memory savings for tiling is however very short term, typically the lifetime of the MTLCommandBuffer.
Attempt to apply a MPSKernel to a texture in place.
Parameter commandBuffer: A valid MTLCommandBuffer to receive the encoded filter
Parameter primaryTexture: A pointer to a valid MTLTexture containing the
primary source image. It will not be overwritten.
Parameter inPlaceSecondaryTexture: A pointer to a valid MTLTexture containing secondary image.
On success, the image contents and possibly texture itself
will be replaced with the result image.
Parameter copyAllocator: An optional block to allocate a new texture to hold the
results, in case in-place operation is not possible. The
allocator may use a different MTLPixelFormat or size than
the original texture. You may enqueue operations on the
provided MTLCommandBuffer using the provided
MTLComputeCommandEncoder to initialize the texture contents.
Returns: On success, YES is returned. The texture may have been replaced with a new texture if a copyAllocator was provided. On failure, NO is returned. The texture is unmodified.
§Safety
primary_texturemay need to be synchronized.primary_texturemay be unretained, you must ensure it is kept alive while in use.in_place_secondary_texturemust be a valid pointer.copy_allocatormust be a valid pointer or null.
Sourcepub unsafe fn encodeToCommandBuffer_inPlacePrimaryTexture_secondaryTexture_fallbackCopyAllocator(
&self,
command_buffer: &ProtocolObject<dyn MTLCommandBuffer>,
in_place_primary_texture: NonNull<NonNull<ProtocolObject<dyn MTLTexture>>>,
secondary_texture: &ProtocolObject<dyn MTLTexture>,
copy_allocator: MPSCopyAllocator,
) -> bool
Available on crate feature block2 only.
pub unsafe fn encodeToCommandBuffer_inPlacePrimaryTexture_secondaryTexture_fallbackCopyAllocator( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, in_place_primary_texture: NonNull<NonNull<ProtocolObject<dyn MTLTexture>>>, secondary_texture: &ProtocolObject<dyn MTLTexture>, copy_allocator: MPSCopyAllocator, ) -> bool
block2 only.Attempt to apply a MPSKernel to a texture in place.
This method attempts to apply the MPSKernel in place on a texture.
In-place operation means that the same texture is used both to hold the input
image and the results. Operating in-place can be an excellent way to reduce
resource utilization, and save time and energy. While simple Metal kernels can
not operate in place because textures can not be readable and writable at the
same time, some MPSKernels can operate in place because they use
multi-pass algorithms. Whether a MPSKernel can operate in-place can
depend on current hardware, operating system revision and the parameters
and properties passed to it. You should never assume that a MPSKernel will
continue to work in place, even if you have observed it doing so before.If the operation succeeds in-place, YES is returned. If the in-place operation fails and no copyAllocator is provided, then NO is returned. In neither case is the pointer held at *texture modified.
Failure during in-place operation is common. You may find it simplifies your code to provide a copyAllocator. When an in-place filter fails, your copyAllocator will be invoked to create a new texture in which to write the results, allowing the filter to proceed reliably out-of-place. The original texture will be released, replaced with a pointer to the new texture and YES will be returned. If the allocator returns an invalid texture, it is released, *texture remains unmodified and NO is returned. Please see the MPSCopyAllocator definition for a sample allocator implementation.
Note: Image filters that look at neighboring pixel values may actually consume more memory when operating in place than out of place. Many such operations are tiled internally to save intermediate texture storage, but can not tile when operating in place. The memory savings for tiling is however very short term, typically the lifetime of the MTLCommandBuffer.
Parameter commandBuffer: A valid MTLCommandBuffer to receive the encoded filter
Parameter inPlacePrimaryTexture: A pointer to a valid MTLTexture containing secondary image.
On success, the image contents and possibly texture itself
will be replaced with the result image.
Parameter secondaryTexture: A pointer to a valid MTLTexture containing the
primary source image. It will not be overwritten.
Parameter copyAllocator: An optional block to allocate a new texture to hold the
results, in case in-place operation is not possible. The
allocator may use a different MTLPixelFormat or size than
the original texture. You may enqueue operations on the
provided MTLCommandBuffer using the provided
MTLComputeCommandEncoder to initialize the texture contents.
Returns: On success, YES is returned. The texture may have been replaced with a new texture if a copyAllocator was provided. On failure, NO is returned. The texture is unmodified.
§Safety
in_place_primary_texturemust be a valid pointer.secondary_texturemay need to be synchronized.secondary_texturemay be unretained, you must ensure it is kept alive while in use.copy_allocatormust be a valid pointer or null.
Sourcepub unsafe fn encodeToCommandBuffer_primaryTexture_secondaryTexture_destinationTexture(
&self,
command_buffer: &ProtocolObject<dyn MTLCommandBuffer>,
primary_texture: &ProtocolObject<dyn MTLTexture>,
secondary_texture: &ProtocolObject<dyn MTLTexture>,
destination_texture: &ProtocolObject<dyn MTLTexture>,
)
pub unsafe fn encodeToCommandBuffer_primaryTexture_secondaryTexture_destinationTexture( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, primary_texture: &ProtocolObject<dyn MTLTexture>, secondary_texture: &ProtocolObject<dyn MTLTexture>, destination_texture: &ProtocolObject<dyn MTLTexture>, )
Encode a MPSKernel into a command Buffer. The operation shall proceed out-of-place.
Parameter commandBuffer: A valid MTLCommandBuffer to receive the encoded filter
Parameter primaryTexture: A valid MTLTexture containing the primary source image.
Parameter secondaryTexture: A valid MTLTexture containing the secondary source image.
Parameter destinationTexture: A valid MTLTexture to be overwritten by result image. destinationTexture may not alias the source textures.
§Safety
primary_texturemay need to be synchronized.primary_texturemay be unretained, you must ensure it is kept alive while in use.secondary_texturemay need to be synchronized.secondary_texturemay be unretained, you must ensure it is kept alive while in use.destination_texturemay need to be synchronized.destination_texturemay be unretained, you must ensure it is kept alive while in use.
Sourcepub unsafe fn encodeToCommandBuffer_primaryImage_secondaryImage_destinationImage(
&self,
command_buffer: &ProtocolObject<dyn MTLCommandBuffer>,
primary_image: &MPSImage,
secondary_image: &MPSImage,
destination_image: &MPSImage,
)
pub unsafe fn encodeToCommandBuffer_primaryImage_secondaryImage_destinationImage( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, primary_image: &MPSImage, secondary_image: &MPSImage, destination_image: &MPSImage, )
Encode a MPSKernel into a command Buffer. The operation shall proceed out-of-place.
Parameter commandBuffer: A valid MTLCommandBuffer to receive the encoded filter
Parameter primaryImage: A valid MPSImage containing the primary source image.
Parameter secondaryImage: A valid MPSImage containing the secondary source image.
Parameter destinationImage: A valid MPSImage to be overwritten by result image. destinationImage may not alias the source images.
Sourcepub unsafe fn primarySourceRegionForDestinationSize(
&self,
destination_size: MTLSize,
) -> MPSRegion
Available on crate feature MPSCoreTypes only.
pub unsafe fn primarySourceRegionForDestinationSize( &self, destination_size: MTLSize, ) -> MPSRegion
MPSCoreTypes only.primarySourceRegionForDestinationSize: is used to determine which region of the primaryTexture will be read by encodeToCommandBuffer:primaryTexture:secondaryTexture:destinationTexture (and in-place variants) when the filter runs. This information may be needed if the primary source image is broken into multiple textures. The size of the full (untiled) destination image is provided. The region of the full (untiled) source image that will be read is returned. You can then piece together an appropriate texture containing that information for use in your tiled context.
The function will consult the MPSBinaryImageKernel primaryOffset and clipRect parameters, to determine the full region read by the function. Other parameters such as kernelHeight and kernelWidth will be consulted as necessary. All properties should be set to intended values prior to calling primarySourceRegionForDestinationSize:.
Caution: This function operates using global image coordinates, but -encodeToCommandBuffer:… uses coordinates local to the source and destination image textures. Consequently, the primaryOffset and clipRect attached to this object will need to be updated using a global to local coordinate transform before -encodeToCommandBuffer:… is called.
Determine the region of the source texture that will be read for a encode operation
Parameter destinationSize: The size of the full virtual destination image.
Returns: The area in the virtual source image that will be read.
Sourcepub unsafe fn secondarySourceRegionForDestinationSize(
&self,
destination_size: MTLSize,
) -> MPSRegion
Available on crate feature MPSCoreTypes only.
pub unsafe fn secondarySourceRegionForDestinationSize( &self, destination_size: MTLSize, ) -> MPSRegion
MPSCoreTypes only.secondarySourceRegionForDestinationSize: is used to determine which region of the sourceTexture will be read by encodeToCommandBuffer:primaryTexture:secondaryTexture:destinationTexture (and in-place variants) when the filter runs. This information may be needed if the secondary source image is broken into multiple textures. The size of the full (untiled) destination image is provided. The region of the full (untiled) secondary source image that will be read is returned. You can then piece together an appropriate texture containing that information for use in your tiled context.
The function will consult the MPSBinaryImageKernel secondaryOffset and clipRect parameters, to determine the full region read by the function. Other parameters such as kernelHeight and kernelWidth will be consulted as necessary. All properties should be set to intended values prior to calling secondarySourceRegionForDestinationSize:.
Caution: This function operates using global image coordinates, but -encodeToCommandBuffer:… uses coordinates local to the source and destination image textures. Consequently, the secondaryOffset and clipRect attached to this object will need to be updated using a global to local coordinate transform before -encodeToCommandBuffer:… is called.
Determine the region of the source texture that will be read for a encode operation
Parameter destinationSize: The size of the full virtual destination image.
Returns: The area in the virtual source image that will be read.
Methods from Deref<Target = MPSKernel>§
Sourcepub unsafe fn options(&self) -> MPSKernelOptions
Available on crate feature MPSCoreTypes only.
pub unsafe fn options(&self) -> MPSKernelOptions
MPSCoreTypes only.The set of options used to run the kernel. subsubsection_options
Sourcepub unsafe fn setOptions(&self, options: MPSKernelOptions)
Available on crate feature MPSCoreTypes only.
pub unsafe fn setOptions(&self, options: MPSKernelOptions)
MPSCoreTypes only.Setter for options.
Sourcepub unsafe fn device(&self) -> Retained<ProtocolObject<dyn MTLDevice>>
pub unsafe fn device(&self) -> Retained<ProtocolObject<dyn MTLDevice>>
The device on which the kernel will be used
Sourcepub unsafe fn label(&self) -> Option<Retained<NSString>>
pub unsafe fn label(&self) -> Option<Retained<NSString>>
A string to help identify this object.
Sourcepub unsafe fn copyWithZone_device(
&self,
zone: *mut NSZone,
device: Option<&ProtocolObject<dyn MTLDevice>>,
) -> Retained<Self>
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>§
Sourcepub fn doesNotRecognizeSelector(&self, sel: Sel) -> !
pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !
Handle messages the object doesn’t recognize.
See Apple’s documentation for details.
Methods from Deref<Target = AnyObject>§
Sourcepub fn class(&self) -> &'static AnyClass
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());Sourcepub unsafe fn get_ivar<T>(&self, name: &str) -> &Twhere
T: Encode,
👎Deprecated: this is difficult to use correctly, use Ivar::load instead.
pub unsafe fn get_ivar<T>(&self, name: &str) -> &Twhere
T: Encode,
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.
Sourcepub fn downcast_ref<T>(&self) -> Option<&T>where
T: DowncastTarget,
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§
Source§impl AsRef<AnyObject> for MPSImageSubtract
impl AsRef<AnyObject> for MPSImageSubtract
Source§impl AsRef<MPSBinaryImageKernel> for MPSImageSubtract
impl AsRef<MPSBinaryImageKernel> for MPSImageSubtract
Source§fn as_ref(&self) -> &MPSBinaryImageKernel
fn as_ref(&self) -> &MPSBinaryImageKernel
Source§impl AsRef<MPSImageArithmetic> for MPSImageSubtract
impl AsRef<MPSImageArithmetic> for MPSImageSubtract
Source§fn as_ref(&self) -> &MPSImageArithmetic
fn as_ref(&self) -> &MPSImageArithmetic
Source§impl AsRef<MPSImageSubtract> for MPSImageSubtract
impl AsRef<MPSImageSubtract> for MPSImageSubtract
Source§impl AsRef<MPSKernel> for MPSImageSubtract
impl AsRef<MPSKernel> for MPSImageSubtract
Source§impl AsRef<NSObject> for MPSImageSubtract
impl AsRef<NSObject> for MPSImageSubtract
Source§impl Borrow<AnyObject> for MPSImageSubtract
impl Borrow<AnyObject> for MPSImageSubtract
Source§impl Borrow<MPSBinaryImageKernel> for MPSImageSubtract
impl Borrow<MPSBinaryImageKernel> for MPSImageSubtract
Source§fn borrow(&self) -> &MPSBinaryImageKernel
fn borrow(&self) -> &MPSBinaryImageKernel
Source§impl Borrow<MPSImageArithmetic> for MPSImageSubtract
impl Borrow<MPSImageArithmetic> for MPSImageSubtract
Source§fn borrow(&self) -> &MPSImageArithmetic
fn borrow(&self) -> &MPSImageArithmetic
Source§impl Borrow<MPSKernel> for MPSImageSubtract
impl Borrow<MPSKernel> for MPSImageSubtract
Source§impl Borrow<NSObject> for MPSImageSubtract
impl Borrow<NSObject> for MPSImageSubtract
Source§impl ClassType for MPSImageSubtract
impl ClassType for MPSImageSubtract
Source§const NAME: &'static str = "MPSImageSubtract"
const NAME: &'static str = "MPSImageSubtract"
Source§type Super = MPSImageArithmetic
type Super = MPSImageArithmetic
Source§type ThreadKind = <<MPSImageSubtract as ClassType>::Super as ClassType>::ThreadKind
type ThreadKind = <<MPSImageSubtract as ClassType>::Super as ClassType>::ThreadKind
Source§impl CopyingHelper for MPSImageSubtract
impl CopyingHelper for MPSImageSubtract
Source§type Result = MPSImageSubtract
type Result = MPSImageSubtract
Self if the type has no
immutable counterpart. Read moreSource§impl Debug for MPSImageSubtract
impl Debug for MPSImageSubtract
Source§impl Deref for MPSImageSubtract
impl Deref for MPSImageSubtract
Source§impl Hash for MPSImageSubtract
impl Hash for MPSImageSubtract
Source§impl Message for MPSImageSubtract
impl Message for MPSImageSubtract
Source§impl NSCoding for MPSImageSubtract
impl NSCoding for MPSImageSubtract
Source§unsafe fn encodeWithCoder(&self, coder: &NSCoder)
unsafe fn encodeWithCoder(&self, coder: &NSCoder)
NSCoder only.Source§impl NSCopying for MPSImageSubtract
impl NSCopying for MPSImageSubtract
Source§impl NSObjectProtocol for MPSImageSubtract
impl NSObjectProtocol for MPSImageSubtract
Source§fn isEqual(&self, other: Option<&AnyObject>) -> bool
fn isEqual(&self, other: Option<&AnyObject>) -> bool
Source§fn hash(&self) -> usize
fn hash(&self) -> usize
Source§fn isKindOfClass(&self, cls: &AnyClass) -> bool
fn isKindOfClass(&self, cls: &AnyClass) -> bool
Source§fn is_kind_of<T>(&self) -> bool
fn is_kind_of<T>(&self) -> bool
use isKindOfClass directly, or cast your objects with AnyObject::downcast_ref