Struct MTLTextureDescriptor

Source

pub struct MTLTextureDescriptor { /* private fields */ }

Available on crate feature MTLTexture only.

Expand description

Apple’s documentation

Implementations§

Source §

impl MTLTextureDescriptor

Source

pub unsafe fn texture2DDescriptorWithPixelFormat_width_height_mipmapped( pixel_format: MTLPixelFormat, width: NSUInteger, height: NSUInteger, mipmapped: bool, ) -> Retained<MTLTextureDescriptor>

Available on crate feature MTLPixelFormat only.

Create a TextureDescriptor for a common 2D texture.

Source

pub unsafe fn textureCubeDescriptorWithPixelFormat_size_mipmapped( pixel_format: MTLPixelFormat, size: NSUInteger, mipmapped: bool, ) -> Retained<MTLTextureDescriptor>

Available on crate feature MTLPixelFormat only.

Create a TextureDescriptor for a common Cube texture.

§Safety

size might not be bounds-checked.

Source

pub unsafe fn textureBufferDescriptorWithPixelFormat_width_resourceOptions_usage( pixel_format: MTLPixelFormat, width: NSUInteger, resource_options: MTLResourceOptions, usage: MTLTextureUsage, ) -> Retained<MTLTextureDescriptor>

Available on crate features MTLPixelFormat and MTLResource only.

Create a TextureDescriptor for a common texture buffer.

Source

pub fn textureType(&self) -> MTLTextureType

The overall type of the texture to be created. The default value is MTLTextureType2D.

Source

pub fn setTextureType(&self, texture_type: MTLTextureType)

Setter for textureType.

Source

pub fn pixelFormat(&self) -> MTLPixelFormat

Available on crate feature MTLPixelFormat only.

The pixel format to use when allocating this texture. This is also the pixel format that will be used to when the caller writes or reads pixels from this texture. The default value is MTLPixelFormatRGBA8Unorm.

Source

pub fn setPixelFormat(&self, pixel_format: MTLPixelFormat)

Available on crate feature MTLPixelFormat only.

Setter for pixelFormat.

Source

pub fn width(&self) -> NSUInteger

The width of the texture to create. The default value is 1.

Source

pub unsafe fn setWidth(&self, width: NSUInteger)

Setter for width.

Source

pub fn height(&self) -> NSUInteger

The height of the texture to create. The default value is 1.

height If allocating a 1D texture, height must be 1.

Source

pub unsafe fn setHeight(&self, height: NSUInteger)

Setter for height.

Source

pub fn depth(&self) -> NSUInteger

The depth of the texture to create. The default value is 1.

depth When allocating any texture types other than 3D, depth must be 1.

Source

pub unsafe fn setDepth(&self, depth: NSUInteger)

Setter for depth.

Source

pub fn mipmapLevelCount(&self) -> NSUInteger

The number of mipmap levels to allocate. The default value is 1.

When creating Buffer and Multisample textures, mipmapLevelCount must be 1.

Source

pub unsafe fn setMipmapLevelCount(&self, mipmap_level_count: NSUInteger)

Setter for mipmapLevelCount.

§Safety

This might not be bounds-checked.

Source

pub fn sampleCount(&self) -> NSUInteger

The number of samples in the texture to create. The default value is 1.

When creating Buffer textures sampleCount must be 1. Implementations may round sample counts up to the next supported value.

Source

pub unsafe fn setSampleCount(&self, sample_count: NSUInteger)

Setter for sampleCount.

§Safety

This might not be bounds-checked.

Source

pub fn arrayLength(&self) -> NSUInteger

The number of array elements to allocate. The default value is 1.

When allocating any non-Array texture type, arrayLength has to be 1. Otherwise it must be set to something greater than 1 and less than 2048.

Source

pub unsafe fn setArrayLength(&self, array_length: NSUInteger)

Setter for arrayLength.

Source

pub fn resourceOptions(&self) -> MTLResourceOptions

Available on crate feature MTLResource only.

Options to control memory allocation parameters, etc.

Contains a packed set of the storageMode, cpuCacheMode and hazardTrackingMode properties.

Source

pub fn setResourceOptions(&self, resource_options: MTLResourceOptions)

Available on crate feature MTLResource only.

Setter for resourceOptions.

Source

pub fn cpuCacheMode(&self) -> MTLCPUCacheMode

Available on crate feature MTLResource only.

Options to specify CPU cache mode of texture resource.

Source

pub fn setCpuCacheMode(&self, cpu_cache_mode: MTLCPUCacheMode)

Available on crate feature MTLResource only.

Setter for cpuCacheMode.

Source

pub fn storageMode(&self) -> MTLStorageMode

Available on crate feature MTLResource only.

To specify storage mode of texture resource.

Source

pub fn setStorageMode(&self, storage_mode: MTLStorageMode)

Available on crate feature MTLResource only.

Setter for storageMode.

Source

pub fn hazardTrackingMode(&self) -> MTLHazardTrackingMode

Available on crate feature MTLResource only.

Set hazard tracking mode for the texture. The default value is MTLHazardTrackingModeDefault.

For resources created from the device, MTLHazardTrackingModeDefault is treated as MTLHazardTrackingModeTracked. For resources created on a heap, MTLHazardTrackingModeDefault is treated as the hazardTrackingMode of the heap itself. In either case, it is possible to opt-out of hazard tracking by setting MTLHazardTrackingModeUntracked. It is not possible to opt-in to hazard tracking on a heap that itself is not hazard tracked. For optimal performance, perform hazard tracking manually through MTLFence or MTLEvent instead.

Source

pub fn setHazardTrackingMode(&self, hazard_tracking_mode: MTLHazardTrackingMode)

Available on crate feature MTLResource only.

Setter for hazardTrackingMode.

Source

pub fn usage(&self) -> MTLTextureUsage

Description of texture usage

Source

pub fn setUsage(&self, usage: MTLTextureUsage)

Setter for usage.

Source

pub fn allowGPUOptimizedContents(&self) -> bool

Allow GPU-optimization for the contents of this texture. The default value is true.

Useful for opting-out of GPU-optimization when implicit optimization (e.g. RT writes) is regressing CPU-read-back performance. See the documentation for optimizeContentsForGPUAccess: and optimizeContentsForCPUAccess: APIs.

Source

pub fn setAllowGPUOptimizedContents(&self, allow_gpu_optimized_contents: bool)

Setter for allowGPUOptimizedContents.

Source

pub fn compressionType(&self) -> MTLTextureCompressionType

Controls how the texture contents will be compressed when written to by the GPU. Compression can be used to reduce the bandwidth usage and storage requirements of a texture.

The default compression type is lossless, meaning that no loss of precision will occur when the texture content is modified. Losslessly compressed textures may benefit from reduced bandwidth usage when regions of correlated color values are written, but do not benefit from reduced storage requirements. Enabling lossy compression for textures that can tolerate some precision loss will guarantee both reduced bandwidth usage and reduced storage requirements. The amount of precision loss depends on the color values stored; regions with correlated color values can be represented with limited to no precision loss, whereas regions with unrelated color values suffer more precision loss. Enabling lossy compression requires both storageMode == MTLStorageModePrivate, allowGPUOptimizedContents == YES, and cannot be combined with either MTLTextureUsagePixelFormatView, MTLTextureUsageShaderWrite, MTLTextureUsageShaderAtomic, MTLTextureType1D(Array) or MTLTextureTypeTextureBuffer. Moreover, not all MTLPixelFormat are supported with lossy compression, verify that the MTLDevice’s GPU family supports the lossy compression feature for the pixelFormat requested. Set allowGPUOptimizedContents to NO to opt out of both lossless and lossy compression; such textures do not benefit from either reduced bandwidth usage or reduced storage requirements, but have predictable CPU readback performance.

Source

pub fn setCompressionType(&self, compression_type: MTLTextureCompressionType)

Setter for compressionType.

Source

pub fn swizzle(&self) -> MTLTextureSwizzleChannels

Channel swizzle to use when reading or sampling from the texture, the default value is MTLTextureSwizzleChannelsDefault.

Source

pub fn setSwizzle(&self, swizzle: MTLTextureSwizzleChannels)

Setter for swizzle.

Source

pub fn placementSparsePageSize(&self) -> MTLSparsePageSize

Available on crate feature MTLResource only.

Determines the page size for a placement sparse texture.

Set this property to a non-zero value to create a placement sparse texture.

Placement sparse textures are instances of MTLTexture that you assign memory to using a MTLHeap instance of type MTLHeapType/MTLHeapTypePlacement and a MTLHeapDescriptor/maxCompatiblePlacementSparsePageSize at least as large as the MTLSparsePageSize value you assign to this property.

This value is 0 by default.

Source

pub fn setPlacementSparsePageSize( &self, placement_sparse_page_size: MTLSparsePageSize, )

Available on crate feature MTLResource only.

Setter for placementSparsePageSize.

Source §

impl MTLTextureDescriptor

Methods declared on superclass NSObject.

Source

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

Source

pub fn new() -> Retained<Self>

Methods from Deref<Target = NSObject>§

Source

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

Handle messages the object doesn’t recognize.

See Apple’s documentation for details.

Methods from Deref<Target = AnyObject>§

Source

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());

Source

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.

Source

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`
    }
}