objc2_metal/generated/
MTLTexture.rs

1//! This file has been automatically generated by `objc2`'s `header-translator`.
2//! DO NOT EDIT
3use core::ffi::*;
4use core::ptr::NonNull;
5use objc2::__framework_prelude::*;
6use objc2_foundation::*;
7#[cfg(feature = "objc2-io-surface")]
8use objc2_io_surface::*;
9
10use crate::*;
11
12/// MTLTextureType describes the dimensionality of each image, and if multiple images are arranged into an array or cube.
13///
14/// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtltexturetype?language=objc)
15// NS_ENUM
16#[repr(transparent)]
17#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
18pub struct MTLTextureType(pub NSUInteger);
19impl MTLTextureType {
20    #[doc(alias = "MTLTextureType1D")]
21    pub const Type1D: Self = Self(0);
22    #[doc(alias = "MTLTextureType1DArray")]
23    pub const Type1DArray: Self = Self(1);
24    #[doc(alias = "MTLTextureType2D")]
25    pub const Type2D: Self = Self(2);
26    #[doc(alias = "MTLTextureType2DArray")]
27    pub const Type2DArray: Self = Self(3);
28    #[doc(alias = "MTLTextureType2DMultisample")]
29    pub const Type2DMultisample: Self = Self(4);
30    #[doc(alias = "MTLTextureTypeCube")]
31    pub const TypeCube: Self = Self(5);
32    #[doc(alias = "MTLTextureTypeCubeArray")]
33    pub const TypeCubeArray: Self = Self(6);
34    #[doc(alias = "MTLTextureType3D")]
35    pub const Type3D: Self = Self(7);
36    #[doc(alias = "MTLTextureType2DMultisampleArray")]
37    pub const Type2DMultisampleArray: Self = Self(8);
38    #[doc(alias = "MTLTextureTypeTextureBuffer")]
39    pub const TypeTextureBuffer: Self = Self(9);
40}
41
42unsafe impl Encode for MTLTextureType {
43    const ENCODING: Encoding = NSUInteger::ENCODING;
44}
45
46unsafe impl RefEncode for MTLTextureType {
47    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
48}
49
50/// [Apple's documentation](https://developer.apple.com/documentation/metal/mtltextureswizzle?language=objc)
51// NS_ENUM
52#[repr(transparent)]
53#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
54pub struct MTLTextureSwizzle(pub u8);
55impl MTLTextureSwizzle {
56    #[doc(alias = "MTLTextureSwizzleZero")]
57    pub const Zero: Self = Self(0);
58    #[doc(alias = "MTLTextureSwizzleOne")]
59    pub const One: Self = Self(1);
60    #[doc(alias = "MTLTextureSwizzleRed")]
61    pub const Red: Self = Self(2);
62    #[doc(alias = "MTLTextureSwizzleGreen")]
63    pub const Green: Self = Self(3);
64    #[doc(alias = "MTLTextureSwizzleBlue")]
65    pub const Blue: Self = Self(4);
66    #[doc(alias = "MTLTextureSwizzleAlpha")]
67    pub const Alpha: Self = Self(5);
68}
69
70unsafe impl Encode for MTLTextureSwizzle {
71    const ENCODING: Encoding = u8::ENCODING;
72}
73
74unsafe impl RefEncode for MTLTextureSwizzle {
75    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
76}
77
78/// [Apple's documentation](https://developer.apple.com/documentation/metal/mtltextureswizzlechannels?language=objc)
79#[repr(C)]
80#[derive(Clone, Copy, Debug, PartialEq)]
81pub struct MTLTextureSwizzleChannels {
82    pub red: MTLTextureSwizzle,
83    pub green: MTLTextureSwizzle,
84    pub blue: MTLTextureSwizzle,
85    pub alpha: MTLTextureSwizzle,
86}
87
88unsafe impl Encode for MTLTextureSwizzleChannels {
89    const ENCODING: Encoding = Encoding::Struct(
90        "?",
91        &[
92            <MTLTextureSwizzle>::ENCODING,
93            <MTLTextureSwizzle>::ENCODING,
94            <MTLTextureSwizzle>::ENCODING,
95            <MTLTextureSwizzle>::ENCODING,
96        ],
97    );
98}
99
100unsafe impl RefEncode for MTLTextureSwizzleChannels {
101    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
102}
103
104impl MTLTextureSwizzleChannels {
105    // TODO: pub fn MTLTextureSwizzleChannelsMake(r: MTLTextureSwizzle,g: MTLTextureSwizzle,b: MTLTextureSwizzle,a: MTLTextureSwizzle,) -> MTLTextureSwizzleChannels;
106}
107
108extern_class!(
109    /// [Apple's documentation](https://developer.apple.com/documentation/metal/mtlsharedtexturehandle?language=objc)
110    #[unsafe(super(NSObject))]
111    #[derive(Debug, PartialEq, Eq, Hash)]
112    pub struct MTLSharedTextureHandle;
113);
114
115extern_conformance!(
116    unsafe impl NSCoding for MTLSharedTextureHandle {}
117);
118
119extern_conformance!(
120    unsafe impl NSObjectProtocol for MTLSharedTextureHandle {}
121);
122
123extern_conformance!(
124    unsafe impl NSSecureCoding for MTLSharedTextureHandle {}
125);
126
127impl MTLSharedTextureHandle {
128    extern_methods!(
129        #[cfg(feature = "MTLDevice")]
130        /// The device this texture was created against.
131        ///
132        /// This shared texture handle can only be used with this device.
133        #[unsafe(method(device))]
134        #[unsafe(method_family = none)]
135        pub fn device(&self) -> Retained<ProtocolObject<dyn MTLDevice>>;
136
137        /// A copy of the original texture's label property, if any
138        #[unsafe(method(label))]
139        #[unsafe(method_family = none)]
140        pub fn label(&self) -> Option<Retained<NSString>>;
141    );
142}
143
144/// Methods declared on superclass `NSObject`.
145impl MTLSharedTextureHandle {
146    extern_methods!(
147        #[unsafe(method(init))]
148        #[unsafe(method_family = init)]
149        pub fn init(this: Allocated<Self>) -> Retained<Self>;
150
151        #[unsafe(method(new))]
152        #[unsafe(method_family = new)]
153        pub fn new() -> Retained<Self>;
154    );
155}
156
157impl DefaultRetained for MTLSharedTextureHandle {
158    #[inline]
159    fn default_retained() -> Retained<Self> {
160        Self::new()
161    }
162}
163
164/// MTLTextureUsage declares how the texture will be used over its lifetime (bitwise OR for multiple uses).
165///
166/// This information may be used by the driver to make optimization decisions.
167///
168/// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtltextureusage?language=objc)
169// NS_OPTIONS
170#[repr(transparent)]
171#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
172pub struct MTLTextureUsage(pub NSUInteger);
173bitflags::bitflags! {
174    impl MTLTextureUsage: NSUInteger {
175        #[doc(alias = "MTLTextureUsageUnknown")]
176        const Unknown = 0x0000;
177        #[doc(alias = "MTLTextureUsageShaderRead")]
178        const ShaderRead = 0x0001;
179        #[doc(alias = "MTLTextureUsageShaderWrite")]
180        const ShaderWrite = 0x0002;
181        #[doc(alias = "MTLTextureUsageRenderTarget")]
182        const RenderTarget = 0x0004;
183        #[doc(alias = "MTLTextureUsagePixelFormatView")]
184        const PixelFormatView = 0x0010;
185        #[doc(alias = "MTLTextureUsageShaderAtomic")]
186        const ShaderAtomic = 0x0020;
187    }
188}
189
190unsafe impl Encode for MTLTextureUsage {
191    const ENCODING: Encoding = NSUInteger::ENCODING;
192}
193
194unsafe impl RefEncode for MTLTextureUsage {
195    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
196}
197
198/// [Apple's documentation](https://developer.apple.com/documentation/metal/mtltexturecompressiontype?language=objc)
199// NS_ENUM
200#[repr(transparent)]
201#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
202pub struct MTLTextureCompressionType(pub NSInteger);
203impl MTLTextureCompressionType {
204    #[doc(alias = "MTLTextureCompressionTypeLossless")]
205    pub const Lossless: Self = Self(0);
206    #[doc(alias = "MTLTextureCompressionTypeLossy")]
207    pub const Lossy: Self = Self(1);
208}
209
210unsafe impl Encode for MTLTextureCompressionType {
211    const ENCODING: Encoding = NSInteger::ENCODING;
212}
213
214unsafe impl RefEncode for MTLTextureCompressionType {
215    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
216}
217
218extern_class!(
219    /// [Apple's documentation](https://developer.apple.com/documentation/metal/mtltexturedescriptor?language=objc)
220    #[unsafe(super(NSObject))]
221    #[derive(Debug, PartialEq, Eq, Hash)]
222    pub struct MTLTextureDescriptor;
223);
224
225extern_conformance!(
226    unsafe impl NSCopying for MTLTextureDescriptor {}
227);
228
229unsafe impl CopyingHelper for MTLTextureDescriptor {
230    type Result = Self;
231}
232
233extern_conformance!(
234    unsafe impl NSObjectProtocol for MTLTextureDescriptor {}
235);
236
237impl MTLTextureDescriptor {
238    extern_methods!(
239        #[cfg(feature = "MTLPixelFormat")]
240        /// Create a TextureDescriptor for a common 2D texture.
241        #[unsafe(method(texture2DDescriptorWithPixelFormat:width:height:mipmapped:))]
242        #[unsafe(method_family = none)]
243        pub unsafe fn texture2DDescriptorWithPixelFormat_width_height_mipmapped(
244            pixel_format: MTLPixelFormat,
245            width: NSUInteger,
246            height: NSUInteger,
247            mipmapped: bool,
248        ) -> Retained<MTLTextureDescriptor>;
249
250        #[cfg(feature = "MTLPixelFormat")]
251        /// Create a TextureDescriptor for a common Cube texture.
252        ///
253        /// # Safety
254        ///
255        /// `size` might not be bounds-checked.
256        #[unsafe(method(textureCubeDescriptorWithPixelFormat:size:mipmapped:))]
257        #[unsafe(method_family = none)]
258        pub unsafe fn textureCubeDescriptorWithPixelFormat_size_mipmapped(
259            pixel_format: MTLPixelFormat,
260            size: NSUInteger,
261            mipmapped: bool,
262        ) -> Retained<MTLTextureDescriptor>;
263
264        #[cfg(all(feature = "MTLPixelFormat", feature = "MTLResource"))]
265        /// Create a TextureDescriptor for a common texture buffer.
266        #[unsafe(method(textureBufferDescriptorWithPixelFormat:width:resourceOptions:usage:))]
267        #[unsafe(method_family = none)]
268        pub unsafe fn textureBufferDescriptorWithPixelFormat_width_resourceOptions_usage(
269            pixel_format: MTLPixelFormat,
270            width: NSUInteger,
271            resource_options: MTLResourceOptions,
272            usage: MTLTextureUsage,
273        ) -> Retained<MTLTextureDescriptor>;
274
275        /// The overall type of the texture to be created. The default value is MTLTextureType2D.
276        #[unsafe(method(textureType))]
277        #[unsafe(method_family = none)]
278        pub fn textureType(&self) -> MTLTextureType;
279
280        /// Setter for [`textureType`][Self::textureType].
281        #[unsafe(method(setTextureType:))]
282        #[unsafe(method_family = none)]
283        pub fn setTextureType(&self, texture_type: MTLTextureType);
284
285        #[cfg(feature = "MTLPixelFormat")]
286        /// 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.
287        #[unsafe(method(pixelFormat))]
288        #[unsafe(method_family = none)]
289        pub fn pixelFormat(&self) -> MTLPixelFormat;
290
291        #[cfg(feature = "MTLPixelFormat")]
292        /// Setter for [`pixelFormat`][Self::pixelFormat].
293        #[unsafe(method(setPixelFormat:))]
294        #[unsafe(method_family = none)]
295        pub fn setPixelFormat(&self, pixel_format: MTLPixelFormat);
296
297        /// The width of the texture to create. The default value is 1.
298        #[unsafe(method(width))]
299        #[unsafe(method_family = none)]
300        pub fn width(&self) -> NSUInteger;
301
302        /// Setter for [`width`][Self::width].
303        #[unsafe(method(setWidth:))]
304        #[unsafe(method_family = none)]
305        pub unsafe fn setWidth(&self, width: NSUInteger);
306
307        /// The height of the texture to create. The default value is 1.
308        ///
309        /// height If allocating a 1D texture, height must be 1.
310        #[unsafe(method(height))]
311        #[unsafe(method_family = none)]
312        pub fn height(&self) -> NSUInteger;
313
314        /// Setter for [`height`][Self::height].
315        #[unsafe(method(setHeight:))]
316        #[unsafe(method_family = none)]
317        pub unsafe fn setHeight(&self, height: NSUInteger);
318
319        /// The depth of the texture to create. The default value is 1.
320        ///
321        /// depth When allocating any texture types other than 3D, depth must be 1.
322        #[unsafe(method(depth))]
323        #[unsafe(method_family = none)]
324        pub fn depth(&self) -> NSUInteger;
325
326        /// Setter for [`depth`][Self::depth].
327        #[unsafe(method(setDepth:))]
328        #[unsafe(method_family = none)]
329        pub unsafe fn setDepth(&self, depth: NSUInteger);
330
331        /// The number of mipmap levels to allocate. The default value is 1.
332        ///
333        /// When creating Buffer and Multisample textures, mipmapLevelCount must be 1.
334        #[unsafe(method(mipmapLevelCount))]
335        #[unsafe(method_family = none)]
336        pub fn mipmapLevelCount(&self) -> NSUInteger;
337
338        /// Setter for [`mipmapLevelCount`][Self::mipmapLevelCount].
339        ///
340        /// # Safety
341        ///
342        /// This might not be bounds-checked.
343        #[unsafe(method(setMipmapLevelCount:))]
344        #[unsafe(method_family = none)]
345        pub unsafe fn setMipmapLevelCount(&self, mipmap_level_count: NSUInteger);
346
347        /// The number of samples in the texture to create. The default value is 1.
348        ///
349        /// When creating Buffer textures sampleCount must be 1. Implementations may round sample counts up to the next supported value.
350        #[unsafe(method(sampleCount))]
351        #[unsafe(method_family = none)]
352        pub fn sampleCount(&self) -> NSUInteger;
353
354        /// Setter for [`sampleCount`][Self::sampleCount].
355        ///
356        /// # Safety
357        ///
358        /// This might not be bounds-checked.
359        #[unsafe(method(setSampleCount:))]
360        #[unsafe(method_family = none)]
361        pub unsafe fn setSampleCount(&self, sample_count: NSUInteger);
362
363        /// The number of array elements to allocate. The default value is 1.
364        ///
365        /// 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.
366        #[unsafe(method(arrayLength))]
367        #[unsafe(method_family = none)]
368        pub fn arrayLength(&self) -> NSUInteger;
369
370        /// Setter for [`arrayLength`][Self::arrayLength].
371        #[unsafe(method(setArrayLength:))]
372        #[unsafe(method_family = none)]
373        pub unsafe fn setArrayLength(&self, array_length: NSUInteger);
374
375        #[cfg(feature = "MTLResource")]
376        /// Options to control memory allocation parameters, etc.
377        ///
378        /// Contains a packed set of the storageMode, cpuCacheMode and hazardTrackingMode properties.
379        #[unsafe(method(resourceOptions))]
380        #[unsafe(method_family = none)]
381        pub fn resourceOptions(&self) -> MTLResourceOptions;
382
383        #[cfg(feature = "MTLResource")]
384        /// Setter for [`resourceOptions`][Self::resourceOptions].
385        #[unsafe(method(setResourceOptions:))]
386        #[unsafe(method_family = none)]
387        pub fn setResourceOptions(&self, resource_options: MTLResourceOptions);
388
389        #[cfg(feature = "MTLResource")]
390        /// Options to specify CPU cache mode of texture resource.
391        #[unsafe(method(cpuCacheMode))]
392        #[unsafe(method_family = none)]
393        pub fn cpuCacheMode(&self) -> MTLCPUCacheMode;
394
395        #[cfg(feature = "MTLResource")]
396        /// Setter for [`cpuCacheMode`][Self::cpuCacheMode].
397        #[unsafe(method(setCpuCacheMode:))]
398        #[unsafe(method_family = none)]
399        pub fn setCpuCacheMode(&self, cpu_cache_mode: MTLCPUCacheMode);
400
401        #[cfg(feature = "MTLResource")]
402        /// To specify storage mode of texture resource.
403        #[unsafe(method(storageMode))]
404        #[unsafe(method_family = none)]
405        pub fn storageMode(&self) -> MTLStorageMode;
406
407        #[cfg(feature = "MTLResource")]
408        /// Setter for [`storageMode`][Self::storageMode].
409        #[unsafe(method(setStorageMode:))]
410        #[unsafe(method_family = none)]
411        pub fn setStorageMode(&self, storage_mode: MTLStorageMode);
412
413        #[cfg(feature = "MTLResource")]
414        /// Set hazard tracking mode for the texture. The default value is MTLHazardTrackingModeDefault.
415        ///
416        /// For resources created from the device, MTLHazardTrackingModeDefault is treated as MTLHazardTrackingModeTracked.
417        /// For resources created on a heap, MTLHazardTrackingModeDefault is treated as the hazardTrackingMode of the heap itself.
418        /// In either case, it is possible to opt-out of hazard tracking by setting MTLHazardTrackingModeUntracked.
419        /// It is not possible to opt-in to hazard tracking on a heap that itself is not hazard tracked.
420        /// For optimal performance, perform hazard tracking manually through MTLFence or MTLEvent instead.
421        #[unsafe(method(hazardTrackingMode))]
422        #[unsafe(method_family = none)]
423        pub fn hazardTrackingMode(&self) -> MTLHazardTrackingMode;
424
425        #[cfg(feature = "MTLResource")]
426        /// Setter for [`hazardTrackingMode`][Self::hazardTrackingMode].
427        #[unsafe(method(setHazardTrackingMode:))]
428        #[unsafe(method_family = none)]
429        pub fn setHazardTrackingMode(&self, hazard_tracking_mode: MTLHazardTrackingMode);
430
431        /// Description of texture usage
432        #[unsafe(method(usage))]
433        #[unsafe(method_family = none)]
434        pub fn usage(&self) -> MTLTextureUsage;
435
436        /// Setter for [`usage`][Self::usage].
437        #[unsafe(method(setUsage:))]
438        #[unsafe(method_family = none)]
439        pub fn setUsage(&self, usage: MTLTextureUsage);
440
441        /// Allow GPU-optimization for the contents of this texture. The default value is true.
442        ///
443        /// 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.
444        #[unsafe(method(allowGPUOptimizedContents))]
445        #[unsafe(method_family = none)]
446        pub fn allowGPUOptimizedContents(&self) -> bool;
447
448        /// Setter for [`allowGPUOptimizedContents`][Self::allowGPUOptimizedContents].
449        #[unsafe(method(setAllowGPUOptimizedContents:))]
450        #[unsafe(method_family = none)]
451        pub fn setAllowGPUOptimizedContents(&self, allow_gpu_optimized_contents: bool);
452
453        /// 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.
454        ///
455        /// The default compression type is lossless, meaning that no loss of precision will occur when the texture content is modified.
456        /// 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.
457        /// Enabling lossy compression for textures that can tolerate some precision loss will guarantee both reduced bandwidth usage and reduced storage requirements.
458        /// 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.
459        /// Enabling lossy compression requires both storageMode == MTLStorageModePrivate, allowGPUOptimizedContents == YES, and cannot be combined with either MTLTextureUsagePixelFormatView, MTLTextureUsageShaderWrite, MTLTextureUsageShaderAtomic, MTLTextureType1D(Array) or MTLTextureTypeTextureBuffer.
460        /// 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.
461        /// 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.
462        #[unsafe(method(compressionType))]
463        #[unsafe(method_family = none)]
464        pub fn compressionType(&self) -> MTLTextureCompressionType;
465
466        /// Setter for [`compressionType`][Self::compressionType].
467        #[unsafe(method(setCompressionType:))]
468        #[unsafe(method_family = none)]
469        pub fn setCompressionType(&self, compression_type: MTLTextureCompressionType);
470
471        /// Channel swizzle to use when reading or sampling from the texture, the default value is MTLTextureSwizzleChannelsDefault.
472        #[unsafe(method(swizzle))]
473        #[unsafe(method_family = none)]
474        pub fn swizzle(&self) -> MTLTextureSwizzleChannels;
475
476        /// Setter for [`swizzle`][Self::swizzle].
477        #[unsafe(method(setSwizzle:))]
478        #[unsafe(method_family = none)]
479        pub fn setSwizzle(&self, swizzle: MTLTextureSwizzleChannels);
480
481        #[cfg(feature = "MTLResource")]
482        /// Determines the page size for a placement sparse texture.
483        ///
484        /// Set this property to a non-zero value to create a *placement sparse texture*.
485        ///
486        /// Placement sparse textures are instances of ``MTLTexture`` that you assign memory to using a ``MTLHeap`` instance
487        /// of type ``MTLHeapType/MTLHeapTypePlacement`` and a ``MTLHeapDescriptor/maxCompatiblePlacementSparsePageSize``
488        /// at least as large as the ``MTLSparsePageSize`` value you assign to this property.
489        ///
490        /// This value is 0 by default.
491        #[unsafe(method(placementSparsePageSize))]
492        #[unsafe(method_family = none)]
493        pub fn placementSparsePageSize(&self) -> MTLSparsePageSize;
494
495        #[cfg(feature = "MTLResource")]
496        /// Setter for [`placementSparsePageSize`][Self::placementSparsePageSize].
497        #[unsafe(method(setPlacementSparsePageSize:))]
498        #[unsafe(method_family = none)]
499        pub fn setPlacementSparsePageSize(&self, placement_sparse_page_size: MTLSparsePageSize);
500    );
501}
502
503/// Methods declared on superclass `NSObject`.
504impl MTLTextureDescriptor {
505    extern_methods!(
506        #[unsafe(method(init))]
507        #[unsafe(method_family = init)]
508        pub fn init(this: Allocated<Self>) -> Retained<Self>;
509
510        #[unsafe(method(new))]
511        #[unsafe(method_family = new)]
512        pub fn new() -> Retained<Self>;
513    );
514}
515
516impl DefaultRetained for MTLTextureDescriptor {
517    #[inline]
518    fn default_retained() -> Retained<Self> {
519        Self::new()
520    }
521}
522
523extern_class!(
524    /// [Apple's documentation](https://developer.apple.com/documentation/metal/mtltextureviewdescriptor?language=objc)
525    #[unsafe(super(NSObject))]
526    #[derive(Debug, PartialEq, Eq, Hash)]
527    pub struct MTLTextureViewDescriptor;
528);
529
530extern_conformance!(
531    unsafe impl NSCopying for MTLTextureViewDescriptor {}
532);
533
534unsafe impl CopyingHelper for MTLTextureViewDescriptor {
535    type Result = Self;
536}
537
538extern_conformance!(
539    unsafe impl NSObjectProtocol for MTLTextureViewDescriptor {}
540);
541
542impl MTLTextureViewDescriptor {
543    extern_methods!(
544        #[cfg(feature = "MTLPixelFormat")]
545        /// A desired pixel format of a texture view.
546        #[unsafe(method(pixelFormat))]
547        #[unsafe(method_family = none)]
548        pub fn pixelFormat(&self) -> MTLPixelFormat;
549
550        #[cfg(feature = "MTLPixelFormat")]
551        /// Setter for [`pixelFormat`][Self::pixelFormat].
552        #[unsafe(method(setPixelFormat:))]
553        #[unsafe(method_family = none)]
554        pub fn setPixelFormat(&self, pixel_format: MTLPixelFormat);
555
556        /// A desired texture view of a texture view.
557        #[unsafe(method(textureType))]
558        #[unsafe(method_family = none)]
559        pub fn textureType(&self) -> MTLTextureType;
560
561        /// Setter for [`textureType`][Self::textureType].
562        #[unsafe(method(setTextureType:))]
563        #[unsafe(method_family = none)]
564        pub fn setTextureType(&self, texture_type: MTLTextureType);
565
566        /// A desired range of mip levels of a texture view.
567        #[unsafe(method(levelRange))]
568        #[unsafe(method_family = none)]
569        pub fn levelRange(&self) -> NSRange;
570
571        /// Setter for [`levelRange`][Self::levelRange].
572        ///
573        /// # Safety
574        ///
575        /// This might not be bounds-checked.
576        #[unsafe(method(setLevelRange:))]
577        #[unsafe(method_family = none)]
578        pub unsafe fn setLevelRange(&self, level_range: NSRange);
579
580        /// A desired range of slices of a texture view.
581        #[unsafe(method(sliceRange))]
582        #[unsafe(method_family = none)]
583        pub fn sliceRange(&self) -> NSRange;
584
585        /// Setter for [`sliceRange`][Self::sliceRange].
586        ///
587        /// # Safety
588        ///
589        /// This might not be bounds-checked.
590        #[unsafe(method(setSliceRange:))]
591        #[unsafe(method_family = none)]
592        pub unsafe fn setSliceRange(&self, slice_range: NSRange);
593
594        /// A desired swizzle format of a texture view.
595        #[unsafe(method(swizzle))]
596        #[unsafe(method_family = none)]
597        pub fn swizzle(&self) -> MTLTextureSwizzleChannels;
598
599        /// Setter for [`swizzle`][Self::swizzle].
600        #[unsafe(method(setSwizzle:))]
601        #[unsafe(method_family = none)]
602        pub fn setSwizzle(&self, swizzle: MTLTextureSwizzleChannels);
603    );
604}
605
606/// Methods declared on superclass `NSObject`.
607impl MTLTextureViewDescriptor {
608    extern_methods!(
609        #[unsafe(method(init))]
610        #[unsafe(method_family = init)]
611        pub fn init(this: Allocated<Self>) -> Retained<Self>;
612
613        #[unsafe(method(new))]
614        #[unsafe(method_family = new)]
615        pub fn new() -> Retained<Self>;
616    );
617}
618
619impl DefaultRetained for MTLTextureViewDescriptor {
620    #[inline]
621    fn default_retained() -> Retained<Self> {
622        Self::new()
623    }
624}
625
626extern_protocol!(
627    /// MTLTexture represents a collection of 1D, 2D, or 3D images.
628    ///
629    /// Each image in a texture is a 1D, 2D, 2DMultisample, or 3D image. The texture contains one or more images arranged in a mipmap stack. If there are multiple mipmap stacks, each one is referred to as a slice of the texture. 1D, 2D, 2DMultisample, and 3D textures have a single slice. In 1DArray and 2DArray textures, every slice is an array element. A Cube texture always has 6 slices, one for each face. In a CubeArray texture, each set of six slices is one element in the array.
630    ///
631    /// Most APIs that operate on individual images in a texture address those images via a tuple of a Slice, and Mipmap Level within that slice.
632    ///
633    /// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtltexture?language=objc)
634    #[cfg(all(feature = "MTLAllocation", feature = "MTLResource"))]
635    pub unsafe trait MTLTexture: MTLResource {
636        /// The resource this texture was created from. It may be a texture or a buffer. If this texture is not reusing storage of another MTLResource, then nil is returned.
637        #[deprecated = "Use parentTexture or buffer instead"]
638        #[unsafe(method(rootResource))]
639        #[unsafe(method_family = none)]
640        fn rootResource(&self) -> Option<Retained<ProtocolObject<dyn MTLResource>>>;
641
642        /// The texture this texture view was created from, or nil if this is not a texture view or it was not created from a texture.
643        #[unsafe(method(parentTexture))]
644        #[unsafe(method_family = none)]
645        fn parentTexture(&self) -> Option<Retained<ProtocolObject<dyn MTLTexture>>>;
646
647        /// The base level of the texture this texture view was created from, or 0 if this is not a texture view.
648        #[unsafe(method(parentRelativeLevel))]
649        #[unsafe(method_family = none)]
650        fn parentRelativeLevel(&self) -> NSUInteger;
651
652        /// The base slice of the texture this texture view was created from, or 0 if this is not a texture view.
653        #[unsafe(method(parentRelativeSlice))]
654        #[unsafe(method_family = none)]
655        fn parentRelativeSlice(&self) -> NSUInteger;
656
657        #[cfg(feature = "MTLBuffer")]
658        /// The buffer this texture view was created from, or nil if this is not a texture view or it was not created from a buffer.
659        #[unsafe(method(buffer))]
660        #[unsafe(method_family = none)]
661        fn buffer(&self) -> Option<Retained<ProtocolObject<dyn MTLBuffer>>>;
662
663        /// The offset of the buffer this texture view was created from, or 0 if this is not a texture view.
664        #[unsafe(method(bufferOffset))]
665        #[unsafe(method_family = none)]
666        fn bufferOffset(&self) -> NSUInteger;
667
668        /// The bytesPerRow of the buffer this texture view was created from, or 0 if this is not a texture view.
669        #[unsafe(method(bufferBytesPerRow))]
670        #[unsafe(method_family = none)]
671        fn bufferBytesPerRow(&self) -> NSUInteger;
672
673        #[cfg(feature = "objc2-io-surface")]
674        /// If this texture was created from an IOSurface, this returns a reference to that IOSurface. iosurface is nil if this texture was not created from an IOSurface.
675        #[unsafe(method(iosurface))]
676        #[unsafe(method_family = none)]
677        fn iosurface(&self) -> Option<Retained<IOSurfaceRef>>;
678
679        /// If this texture was created from an IOSurface, this returns the plane of the IOSurface from which the texture was created. iosurfacePlane is 0 if this texture was not created from an IOSurface.
680        #[unsafe(method(iosurfacePlane))]
681        #[unsafe(method_family = none)]
682        fn iosurfacePlane(&self) -> NSUInteger;
683
684        /// The type of this texture.
685        #[unsafe(method(textureType))]
686        #[unsafe(method_family = none)]
687        fn textureType(&self) -> MTLTextureType;
688
689        #[cfg(feature = "MTLPixelFormat")]
690        /// The MTLPixelFormat that is used to interpret this texture's contents.
691        #[unsafe(method(pixelFormat))]
692        #[unsafe(method_family = none)]
693        fn pixelFormat(&self) -> MTLPixelFormat;
694
695        /// The width of the MTLTexture instance in pixels.
696        #[unsafe(method(width))]
697        #[unsafe(method_family = none)]
698        fn width(&self) -> NSUInteger;
699
700        /// The height of the MTLTexture instance in pixels.
701        ///
702        /// . height is 1 if the texture is 1D.
703        #[unsafe(method(height))]
704        #[unsafe(method_family = none)]
705        fn height(&self) -> NSUInteger;
706
707        /// The depth of this MTLTexture instance in pixels.
708        ///
709        /// If this MTLTexture is not a 3D texture, the depth is 1
710        #[unsafe(method(depth))]
711        #[unsafe(method_family = none)]
712        fn depth(&self) -> NSUInteger;
713
714        /// The number of mipmap levels in each slice of this MTLTexture.
715        #[unsafe(method(mipmapLevelCount))]
716        #[unsafe(method_family = none)]
717        fn mipmapLevelCount(&self) -> NSUInteger;
718
719        /// The number of samples in each pixel of this MTLTexture.
720        ///
721        /// If this texture is any type other than 2DMultisample, samples is 1.
722        #[unsafe(method(sampleCount))]
723        #[unsafe(method_family = none)]
724        fn sampleCount(&self) -> NSUInteger;
725
726        /// The number of array elements in this MTLTexture.
727        ///
728        /// For non-Array texture types, arrayLength is 1.
729        #[unsafe(method(arrayLength))]
730        #[unsafe(method_family = none)]
731        fn arrayLength(&self) -> NSUInteger;
732
733        /// Description of texture usage.
734        #[unsafe(method(usage))]
735        #[unsafe(method_family = none)]
736        fn usage(&self) -> MTLTextureUsage;
737
738        /// If YES, this texture can be shared with other processes.
739        ///
740        /// Texture can be shared across process addres space boundaries through use of sharedTextureHandle and XPC.
741        #[unsafe(method(isShareable))]
742        #[unsafe(method_family = none)]
743        fn isShareable(&self) -> bool;
744
745        /// If YES, this texture can only be used with a MTLAttachmentDescriptor, and cannot be used as a texture argument for MTLRenderCommandEncoder, MTLBlitCommandEncoder, or MTLComputeCommandEncoder. Furthermore, when this property's value is YES, readPixels/writePixels may not be used with this texture.
746        ///
747        /// Textures obtained from CAMetalDrawables may have this property set to YES, depending on the value of frameBufferOnly passed to their parent CAMetalLayer. Textures created directly by the application will not have any restrictions.
748        #[unsafe(method(isFramebufferOnly))]
749        #[unsafe(method_family = none)]
750        fn isFramebufferOnly(&self) -> bool;
751
752        /// For sparse textures this property returns index of first mipmap that is packed in tail.
753        /// Mapping this mipmap level will map all subsequent mipmap levels.
754        #[optional]
755        #[unsafe(method(firstMipmapInTail))]
756        #[unsafe(method_family = none)]
757        fn firstMipmapInTail(&self) -> NSUInteger;
758
759        /// Amount of memory in bytes required to map sparse texture tail.
760        #[optional]
761        #[unsafe(method(tailSizeInBytes))]
762        #[unsafe(method_family = none)]
763        fn tailSizeInBytes(&self) -> NSUInteger;
764
765        #[optional]
766        #[unsafe(method(isSparse))]
767        #[unsafe(method_family = none)]
768        fn isSparse(&self) -> bool;
769
770        /// Allow GPU-optimization for the contents texture. The default value is true.
771        ///
772        /// 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.
773        #[unsafe(method(allowGPUOptimizedContents))]
774        #[unsafe(method_family = none)]
775        fn allowGPUOptimizedContents(&self) -> bool;
776
777        /// Returns the compression type of the texture
778        ///
779        /// See the compressionType property on MTLTextureDescriptor
780        #[unsafe(method(compressionType))]
781        #[unsafe(method_family = none)]
782        fn compressionType(&self) -> MTLTextureCompressionType;
783
784        #[cfg(feature = "MTLTypes")]
785        /// Handle of the GPU resource suitable for storing in an Argument Buffer
786        #[unsafe(method(gpuResourceID))]
787        #[unsafe(method_family = none)]
788        fn gpuResourceID(&self) -> MTLResourceID;
789
790        #[cfg(feature = "MTLTypes")]
791        /// Copies a block of pixels from a texture slice into the application's memory.
792        ///
793        /// # Safety
794        ///
795        /// `pixel_bytes` must be a valid pointer.
796        #[unsafe(method(getBytes:bytesPerRow:bytesPerImage:fromRegion:mipmapLevel:slice:))]
797        #[unsafe(method_family = none)]
798        unsafe fn getBytes_bytesPerRow_bytesPerImage_fromRegion_mipmapLevel_slice(
799            &self,
800            pixel_bytes: NonNull<c_void>,
801            bytes_per_row: NSUInteger,
802            bytes_per_image: NSUInteger,
803            region: MTLRegion,
804            level: NSUInteger,
805            slice: NSUInteger,
806        );
807
808        #[cfg(feature = "MTLTypes")]
809        /// Copy a block of pixel data from the caller's pointer into a texture slice.
810        ///
811        /// # Safety
812        ///
813        /// `pixel_bytes` must be a valid pointer.
814        #[unsafe(method(replaceRegion:mipmapLevel:slice:withBytes:bytesPerRow:bytesPerImage:))]
815        #[unsafe(method_family = none)]
816        unsafe fn replaceRegion_mipmapLevel_slice_withBytes_bytesPerRow_bytesPerImage(
817            &self,
818            region: MTLRegion,
819            level: NSUInteger,
820            slice: NSUInteger,
821            pixel_bytes: NonNull<c_void>,
822            bytes_per_row: NSUInteger,
823            bytes_per_image: NSUInteger,
824        );
825
826        #[cfg(feature = "MTLTypes")]
827        /// Convenience for getBytes:bytesPerRow:bytesPerImage:fromRegion:mipmapLevel:slice: that doesn't require slice related arguments
828        ///
829        /// # Safety
830        ///
831        /// `pixel_bytes` must be a valid pointer.
832        #[unsafe(method(getBytes:bytesPerRow:fromRegion:mipmapLevel:))]
833        #[unsafe(method_family = none)]
834        unsafe fn getBytes_bytesPerRow_fromRegion_mipmapLevel(
835            &self,
836            pixel_bytes: NonNull<c_void>,
837            bytes_per_row: NSUInteger,
838            region: MTLRegion,
839            level: NSUInteger,
840        );
841
842        #[cfg(feature = "MTLTypes")]
843        /// Convenience for replaceRegion:mipmapLevel:slice:withBytes:bytesPerRow:bytesPerImage: that doesn't require slice related arguments
844        ///
845        /// # Safety
846        ///
847        /// `pixel_bytes` must be a valid pointer.
848        #[unsafe(method(replaceRegion:mipmapLevel:withBytes:bytesPerRow:))]
849        #[unsafe(method_family = none)]
850        unsafe fn replaceRegion_mipmapLevel_withBytes_bytesPerRow(
851            &self,
852            region: MTLRegion,
853            level: NSUInteger,
854            pixel_bytes: NonNull<c_void>,
855            bytes_per_row: NSUInteger,
856        );
857
858        #[cfg(feature = "MTLPixelFormat")]
859        /// Create a new texture which shares the same storage as the source texture, but with a different (but compatible) pixel format.
860        #[unsafe(method(newTextureViewWithPixelFormat:))]
861        #[unsafe(method_family = new)]
862        fn newTextureViewWithPixelFormat(
863            &self,
864            pixel_format: MTLPixelFormat,
865        ) -> Option<Retained<ProtocolObject<dyn MTLTexture>>>;
866
867        #[cfg(feature = "MTLPixelFormat")]
868        /// Create a new texture which shares the same storage as the source texture, but with a different (but compatible) pixel format, texture type, levels and slices.
869        ///
870        /// # Safety
871        ///
872        /// - `levelRange` might not be bounds-checked.
873        /// - `sliceRange` might not be bounds-checked.
874        #[unsafe(method(newTextureViewWithPixelFormat:textureType:levels:slices:))]
875        #[unsafe(method_family = new)]
876        unsafe fn newTextureViewWithPixelFormat_textureType_levels_slices(
877            &self,
878            pixel_format: MTLPixelFormat,
879            texture_type: MTLTextureType,
880            level_range: NSRange,
881            slice_range: NSRange,
882        ) -> Option<Retained<ProtocolObject<dyn MTLTexture>>>;
883
884        /// Create a new texture handle, that can be shared across process addres space boundaries.
885        #[unsafe(method(newSharedTextureHandle))]
886        #[unsafe(method_family = new)]
887        fn newSharedTextureHandle(&self) -> Option<Retained<MTLSharedTextureHandle>>;
888
889        /// Create a new texture which shares the same storage as the source texture, but with different (but compatible) properties specified by the descriptor
890        #[unsafe(method(newTextureViewWithDescriptor:))]
891        #[unsafe(method_family = new)]
892        fn newTextureViewWithDescriptor(
893            &self,
894            descriptor: &MTLTextureViewDescriptor,
895        ) -> Option<Retained<ProtocolObject<dyn MTLTexture>>>;
896
897        /// For Metal texture objects that are remote views, this returns the texture associated with the storage on the originating device.
898        #[unsafe(method(remoteStorageTexture))]
899        #[unsafe(method_family = none)]
900        fn remoteStorageTexture(&self) -> Option<Retained<ProtocolObject<dyn MTLTexture>>>;
901
902        #[cfg(feature = "MTLDevice")]
903        /// On Metal devices that support peer to peer transfers, this method is used to create a remote texture view on another device
904        /// within the peer group.  The receiver must use MTLStorageModePrivate or be backed by an IOSurface.
905        #[unsafe(method(newRemoteTextureViewForDevice:))]
906        #[unsafe(method_family = new)]
907        fn newRemoteTextureViewForDevice(
908            &self,
909            device: &ProtocolObject<dyn MTLDevice>,
910        ) -> Option<Retained<ProtocolObject<dyn MTLTexture>>>;
911
912        /// The channel swizzle used when reading or sampling from this texture
913        #[unsafe(method(swizzle))]
914        #[unsafe(method_family = none)]
915        fn swizzle(&self) -> MTLTextureSwizzleChannels;
916
917        #[cfg(feature = "MTLPixelFormat")]
918        /// Create a new texture which shares the same storage as the source texture, but with a different (but compatible) pixel format, texture type, levels, slices and swizzle.
919        ///
920        /// # Safety
921        ///
922        /// - `levelRange` might not be bounds-checked.
923        /// - `sliceRange` might not be bounds-checked.
924        #[unsafe(method(newTextureViewWithPixelFormat:textureType:levels:slices:swizzle:))]
925        #[unsafe(method_family = new)]
926        unsafe fn newTextureViewWithPixelFormat_textureType_levels_slices_swizzle(
927            &self,
928            pixel_format: MTLPixelFormat,
929            texture_type: MTLTextureType,
930            level_range: NSRange,
931            slice_range: NSRange,
932            swizzle: MTLTextureSwizzleChannels,
933        ) -> Option<Retained<ProtocolObject<dyn MTLTexture>>>;
934
935        /// Query support tier for sparse textures.
936        #[unsafe(method(sparseTextureTier))]
937        #[unsafe(method_family = none)]
938        fn sparseTextureTier(&self) -> MTLTextureSparseTier;
939    }
940);
objc2_metal/generated/MTLTexture.rs

objc2_metal/generated/
MTLTexture.rs
