external_memory/
lib.rs

1#[cfg(any(unix, doc))]
2mod fd;
3#[cfg(any(unix, doc))]
4pub use fd::*;
5
6#[cfg(any(windows, doc))]
7mod handle;
8#[cfg(any(windows, doc))]
9pub use handle::*;
10
11mod ptr;
12pub use ptr::*;
13
14pub use drm_fourcc::DrmModifier;
15use std::ops::Range;
16
17/// Representation of an os specific memory.
18pub enum PlatformMemory {
19    #[cfg(any(unix, doc))]
20    /// Unix file descriptor.
21    Fd(Fd),
22    #[cfg(any(windows, doc))]
23    /// Windows handle.
24    Handle(Handle),
25    /// Host pointer.
26    Ptr(Ptr),
27}
28impl PlatformMemory {
29    #[cfg(any(unix, doc))]
30    pub fn fd(&self)->Option<&Fd> {
31        match self {
32            Self::Fd(fd)=>Some(fd),
33            #[cfg(windows)]
34            Self::Handle(_)=>None,
35            Self::Ptr(_)=>None,
36        }
37    }
38    #[cfg(any(windows, doc))]
39    pub fn handle(&self)->Option<&Handle> {
40        match self {
41            Self::Handle(handle)=>Some(handle),
42            #[cfg(unix)]
43            Self::Fd(_)=>None,
44            Self::Ptr(_)=>None,
45        }
46    }
47    pub fn ptr(&self)->Option<&Ptr> {
48        match self {
49            Self::Ptr(ptr)=>Some(ptr),
50            #[cfg(unix)]
51            Self::Fd(_)=>None,
52            #[cfg(windows)]
53            Self::Handle(_)=>None
54        }
55    }
56}
57
58#[cfg(any(unix, doc))]
59impl std::convert::TryInto<Fd> for PlatformMemory{
60    type Error = &'static str;
61    fn try_into(self) -> Result<Fd, Self::Error>{
62        match self {
63            Self::Fd(fd)=>Ok(fd),
64            #[cfg(windows)]
65            Self::Handle(_)=>Err("PlatformMemory does not contain an fd"),
66            Self::Ptr(_)=>Err("PlatformMemory does not contain an fd"),
67        }
68    }
69}
70
71#[cfg(any(windows, doc))]
72impl std::convert::TryInto<Handle> for PlatformMemory{
73    type Error = &'static str;
74    fn try_into(self) -> Result<Handle, Self::Error>{
75        match self {
76            Self::Handle(handle)=>Ok(handle),
77            #[cfg(unix)]
78            Self::Fd(_)=>Err("PlatformMemory does not contain an handle"),
79            Self::Ptr(_)=>Err("PlatformMemory does not contain an handle"),
80        }
81    }
82}
83
84
85impl std::convert::TryInto<Ptr> for PlatformMemory{
86    type Error = &'static str;
87    fn try_into(self) -> Result<Ptr, Self::Error>{
88        match self {
89            Self::Ptr(ptr)=>Ok(ptr),
90            #[cfg(unix)]
91            Self::Fd(_)=>Err("PlatformMemory does not contain a ptr"),
92            #[cfg(windows)]
93            Self::Handle(_)=>Err("PlatformMemory does not contain a ptr")
94        }
95    }
96}
97
98#[cfg(any(unix,docs))]
99impl From<Fd> for PlatformMemory {
100    fn from(fd: Fd) -> Self {
101        Self::Fd(fd)
102    }
103}
104
105#[cfg(any(windows,doc))]
106impl From<Handle> for PlatformMemory {
107    fn from(handle: Handle) -> Self {
108        Self::Handle(handle)
109    }
110}
111
112impl From<Ptr> for PlatformMemory {
113    fn from(ptr: Ptr) -> Self {
114        Self::Ptr(ptr)
115    }
116}
117
118/// Representation of os specific memory types.
119pub enum PlatformMemoryType {
120    #[cfg(any(unix, doc))]
121    Fd,
122    #[cfg(any(windows, doc))]
123    Handle,
124    Ptr,
125}
126
127
128bitflags::bitflags!(
129    /// External memory type flags.
130    #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
131    pub struct ExternalMemoryTypeFlags: u32 {
132        #[cfg(any(unix,doc))]
133        /// This is supported on Unix only.
134        /// Specifies a POSIX file descriptor handle that has only limited valid usage outside of Vulkan and other compatible APIs.
135        /// It must be compatible with the POSIX system calls dup, dup2, close, and the non-standard system call dup3.
136        /// Additionally, it must be transportable over a socket using an SCM_RIGHTS control message.
137        /// It owns a reference to the underlying memory resource represented by its memory object.
138        const OPAQUE_FD = 0x00000001;
139        #[cfg(any(windows,doc))]
140        /// This is supported on Windows only.
141        /// Specifies an NT handle that has only limited valid usage outside of Vulkan and other compatible APIs.
142        /// It must be compatible with the functions DuplicateHandle, CloseHandle, CompareObjectHandles, GetHandleInformation, and SetHandleInformation.
143        /// It owns a reference to the underlying memory resource represented by its memory object.
144        const OPAQUE_WIN32 = 0x00000002;
145        #[cfg(any(windows,doc))]
146        /// This is supported on Windows only.
147        /// Specifies a global share handle that has only limited valid usage outside of Vulkan and other compatible APIs.
148        /// It is not compatible with any native APIs.
149        /// It does not own a reference to the underlying memory resource represented by its memory object, and will therefore become invalid when all the memory objects with it are destroyed.
150        const OPAQUE_WIN32_KMT = 0x00000004;
151        #[cfg(any(windows,doc))]
152        /// This is supported on Windows only.
153        /// Specifies an NT handle returned by IDXGIResource1::CreateSharedHandle referring to a Direct3D 10 or 11 texture resource.
154        /// It owns a reference to the memory used by the Direct3D resource.
155        const D3D11_TEXTURE = 0x00000008;
156        #[cfg(any(windows,doc))]
157        /// This is supported on Windows only.
158        /// Specifies a global share handle returned by IDXGIResource::GetSharedHandle referring to a Direct3D 10 or 11 texture resource.
159        /// It does not own a reference to the underlying Direct3D resource, and will therefore become invalid when all the memory objects and Direct3D resources associated with it are destroyed.
160        const D3D11_TEXTURE_KMT = 0x00000010;
161        #[cfg(any(windows,doc))]
162        /// This is supported on Windows only.
163        /// Specifies an NT handle returned by ID3D12Device::CreateSharedHandle referring to a Direct3D 12 heap resource.
164        /// It owns a reference to the resources used by the Direct3D heap.
165        const D3D12_HEAP = 0x00000020;
166        #[cfg(any(windows,doc))]
167        /// This is supported on Windows only.
168        /// Specifies an NT handle returned by ID3D12Device::CreateSharedHandle referring to a Direct3D 12 committed resource.
169        /// It owns a reference to the memory used by the Direct3D resource.
170        const D3D12_RESOURCE = 0x00000040;
171        #[cfg(any(target_os = "linux",target_os = "android",doc))]
172        /// This is supported on Linux or Android only.
173        /// Is a file descriptor for a Linux dma_buf.
174        /// It owns a reference to the underlying memory resource represented by its memory object.
175        const DMA_BUF = 0x00000200;
176        #[cfg(any(target_os = "android",doc))]
177        /// This is supported on Android only.
178        /// Specifies an AHardwareBuffer object defined by the Android NDK. See Android Hardware Buffers for more details of this handle type.
179        const ANDROID_HARDWARE_BUFFER = 0x00000400;
180        /// Specifies a host pointer returned by a host memory allocation command.
181        /// It does not own a reference to the underlying memory resource, and will therefore become invalid if the host memory is freed.
182        const HOST_ALLOCATION = 0x00000080;
183        /// Specifies a host pointer to host mapped foreign memory.
184        /// It does not own a reference to the underlying memory resource, and will therefore become invalid if the foreign memory is unmapped or otherwise becomes no longer available.
185        const HOST_MAPPED_FOREIGN_MEMORY = 0x00000100;
186    }
187);
188
189impl From<ExternalMemoryType> for ExternalMemoryTypeFlags {
190    fn from(external_memory_type: ExternalMemoryType) -> Self {
191        match external_memory_type {
192            #[cfg(unix)]
193            ExternalMemoryType::OpaqueFd => Self::OPAQUE_FD,
194            #[cfg(windows)]
195            ExternalMemoryType::OpaqueWin32 => Self::OPAQUE_WIN32,
196            #[cfg(windows)]
197            ExternalMemoryType::OpaqueWin32Kmt => Self::OPAQUE_WIN32_KMT,
198            #[cfg(windows)]
199            ExternalMemoryType::D3D11Texture => Self::D3D11_TEXTURE,
200            #[cfg(windows)]
201            ExternalMemoryType::D3D11TextureKmt => Self::D3D11_TEXTURE_KMT,
202            #[cfg(windows)]
203            ExternalMemoryType::D3D12Heap => Self::D3D12_HEAP,
204            #[cfg(windows)]
205            ExternalMemoryType::D3D12Resource => Self::D3D12_RESOURCE,
206            #[cfg(any(target_os = "linux", target_os = "android", doc))]
207            ExternalMemoryType::DmaBuf => Self::DMA_BUF,
208            #[cfg(target_os = "android")]
209            ExternalMemoryType::AndroidHardwareBuffer => Self::ANDROID_HARDWARE_BUFFER,
210            ExternalMemoryType::HostAllocation => Self::HOST_ALLOCATION,
211            ExternalMemoryType::HostMappedForeignMemory => Self::HOST_MAPPED_FOREIGN_MEMORY,
212        }
213    }
214}
215
216impl From<ExternalImageMemoryType> for ExternalMemoryTypeFlags {
217    fn from(external_memory_type: ExternalImageMemoryType) -> Self {
218        match external_memory_type {
219            #[cfg(unix)]
220            ExternalImageMemoryType::OpaqueFd => Self::OPAQUE_FD,
221            #[cfg(windows)]
222            ExternalImageMemoryType::OpaqueWin32 => Self::OPAQUE_WIN32,
223            #[cfg(windows)]
224            ExternalImageMemoryType::OpaqueWin32Kmt => Self::OPAQUE_WIN32_KMT,
225            #[cfg(windows)]
226            ExternalImageMemoryType::D3D11Texture => Self::D3D11_TEXTURE,
227            #[cfg(windows)]
228            ExternalImageMemoryType::D3D11TextureKmt => Self::D3D11_TEXTURE_KMT,
229            #[cfg(windows)]
230            ExternalImageMemoryType::D3D12Heap => Self::D3D12_HEAP,
231            #[cfg(windows)]
232            ExternalImageMemoryType::D3D12Resource => Self::D3D12_RESOURCE,
233            #[cfg(any(target_os = "linux", target_os = "android", doc))]
234            ExternalImageMemoryType::DmaBuf(_) => Self::DMA_BUF,
235            #[cfg(target_os = "android")]
236            ExternalImageMemoryType::AndroidHardwareBuffer => Self::ANDROID_HARDWARE_BUFFER,
237            ExternalImageMemoryType::HostAllocation => Self::HOST_ALLOCATION,
238            ExternalImageMemoryType::HostMappedForeignMemory => Self::HOST_MAPPED_FOREIGN_MEMORY,
239        }
240    }
241}
242
243/// External memory types.
244#[derive(Clone, Copy, Debug, PartialEq)]
245pub enum ExternalMemoryType {
246    #[cfg(any(unix, doc))]
247    /// This is supported on Unix only.
248    /// Same as [ExternalMemoryTypeFlags::OPAQUE_FD][ExternalMemoryTypeFlags::OPAQUE_FD].
249    OpaqueFd,
250    #[cfg(any(windows, doc))]
251    /// This is supported on Windows only.
252    /// Same as [ExternalMemoryTypeFlags::OPAQUE_WIN32][ExternalMemoryTypeFlags::OPAQUE_WIN32].
253    OpaqueWin32,
254    #[cfg(any(windows, doc))]
255    /// This is supported on Windows only.
256    /// Same as [ExternalMemoryTypeFlags::OPAQUE_WIN32_KMT][ExternalMemoryTypeFlags::OPAQUE_WIN32_KMT].
257    OpaqueWin32Kmt,
258    #[cfg(any(windows, doc))]
259    /// This is supported on Windows only.
260    /// Same as [ExternalMemoryTypeFlags::D3D11_TEXTURE][ExternalMemoryTypeFlags::D3D11_TEXTURE].
261    D3D11Texture,
262    #[cfg(any(windows, doc))]
263    /// This is supported on Windows only.
264    /// Same as [ExternalMemoryTypeFlags::D3D11_TEXTURE_KMT][ExternalMemoryTypeFlags::D3D11_TEXTURE_KMT].
265    D3D11TextureKmt,
266    #[cfg(any(windows, doc))]
267    /// This is supported on Windows only.
268    /// Same as [ExternalMemoryTypeFlags::D3D12_HEAP][ExternalMemoryTypeFlags::D3D12_HEAP].
269    D3D12Heap,
270    #[cfg(any(windows, doc))]
271    /// This is supported on Windows only.
272    /// Same as [ExternalMemoryTypeFlags::D3D12_RESOURCE][ExternalMemoryTypeFlags::D3D12_RESOURCE].
273    D3D12Resource,
274    #[cfg(any(target_os = "linux", target_os = "android", doc))]
275    /// This is supported on Linux or Android only.
276    /// Same as [ExternalMemoryTypeFlags::DMA_BUF][ExternalMemoryTypeFlags::DMA_BUF].
277    DmaBuf,
278    #[cfg(any(target_os = "android", doc))]
279    /// This is supported on Android only.
280    /// Same as [ExternalMemoryTypeFlags::ANDROID_HARDWARE_BUFFER][ExternalMemoryTypeFlags::ANDROID_HARDWARE_BUFFER].
281    AndroidHardwareBuffer,
282    /// Same as [ExternalMemoryTypeFlags::HOST_ALLOCATION][ExternalMemoryTypeFlags::HOST_ALLOCATION].
283    HostAllocation,
284    /// Same as [ExternalMemoryTypeFlags::HOST_MAPPED_FOREIGN_MEMORY][ExternalMemoryTypeFlags::HOST_MAPPED_FOREIGN_MEMORY].
285    HostMappedForeignMemory,
286}
287
288impl Into<PlatformMemoryType> for ExternalMemoryType {
289    fn into(self) -> PlatformMemoryType {
290        match self {
291            #[cfg(unix)]
292            ExternalMemoryType::OpaqueFd => PlatformMemoryType::Fd,
293            #[cfg(windows)]
294            ExternalMemoryType::OpaqueWin32 => PlatformMemoryType::Handle,
295            #[cfg(windows)]
296            ExternalMemoryType::OpaqueWin32Kmt => PlatformMemoryType::Handle,
297            #[cfg(windows)]
298            ExternalMemoryType::D3D11Texture => PlatformMemoryType::Handle,
299            #[cfg(windows)]
300            ExternalMemoryType::D3D11TextureKmt => PlatformMemoryType::Handle,
301            #[cfg(windows)]
302            ExternalMemoryType::D3D12Heap => PlatformMemoryType::Handle,
303            #[cfg(windows)]
304            ExternalMemoryType::D3D12Resource => PlatformMemoryType::Handle,
305            #[cfg(any(target_os = "linux", target_os = "android", doc))]
306            ExternalMemoryType::DmaBuf => PlatformMemoryType::Fd,
307            #[cfg(any(target_os = "android", doc))]
308            ExternalMemoryType::AndroidHardwareBuffer => PlatformMemoryType::Fd,
309            ExternalMemoryType::HostAllocation => PlatformMemoryType::Ptr,
310            ExternalMemoryType::HostMappedForeignMemory => PlatformMemoryType::Ptr,
311        }
312    }
313}
314
315/// Representation of an external memory for buffer creation.
316#[derive(Debug)]
317pub enum ExternalBufferMemory {
318    #[cfg(unix)]
319    /// This is supported on Unix only.
320    /// Same as [ExternalMemoryTypeFlags::OPAQUE_FD][ExternalMemoryTypeFlags::OPAQUE_FD] while holding a [Fd][Fd].
321    OpaqueFd(Fd),
322    #[cfg(windows)]
323    /// This is supported on Windows only.
324    /// Same as [ExternalMemoryTypeFlags::OPAQUE_WIN32][ExternalMemoryTypeFlags::OPAQUE_WIN32] while holding a [Handle][Handle].
325    OpaqueWin32(Handle),
326    #[cfg(windows)]
327    /// This is supported on Windows only.
328    /// Same as [ExternalMemoryTypeFlags::OPAQUE_WIN32_KMT][ExternalMemoryTypeFlags::OPAQUE_WIN32_KMT] while holding a [Handle][Handle].
329    OpaqueWin32Kmt(Handle),
330    #[cfg(windows)]
331    /// This is supported on Windows only.
332    /// Same as [ExternalMemoryTypeFlags::D3D11_TEXTURE][ExternalMemoryTypeFlags::D3D11_TEXTURE] while holding a [Handle][Handle].
333    D3D11Texture(Handle),
334    #[cfg(windows)]
335    /// This is supported on Windows only.
336    /// Same as [ExternalMemoryTypeFlags::D3D11_TEXTURE_KMT][ExternalMemoryTypeFlags::D3D11_TEXTURE_KMT] while holding a [Handle][Handle].
337    D3D11TextureKmt(Handle),
338    #[cfg(windows)]
339    /// This is supported on Windows only.
340    /// Same as [ExternalMemoryTypeFlags::D3D12_HEAP][ExternalMemoryTypeFlags::D3D12_HEAP] while holding a [Handle][Handle].
341    D3D12Heap(Handle),
342    #[cfg(windows)]
343    /// This is supported on Windows only.
344    /// Same as [ExternalMemoryTypeFlags::D3D12_RESOURCE][ExternalMemoryTypeFlags::D3D12_RESOURCE] while holding a [Handle][Handle].
345    D3D12Resource(Handle),
346    #[cfg(any(target_os = "linux", target_os = "android"))]
347    /// This is supported on Linux or Android only.
348    /// Same as [ExternalMemoryTypeFlags::DMA_BUF][ExternalMemoryTypeFlags::DMA_BUF] while holding a [Fd][Fd].
349    DmaBuf(Fd),
350    #[cfg(any(target_os = "android"))]
351    /// This is supported on Android only.
352    /// Same as [ExternalMemoryTypeFlags::ANDROID_HARDWARE_BUFFER][ExternalMemoryTypeFlags::ANDROID_HARDWARE_BUFFER] while holding a [Fd][Fd].
353    AndroidHardwareBuffer(Fd),
354    /// Same as [ExternalMemoryTypeFlags::HOST_ALLOCATION][ExternalMemoryTypeFlags::HOST_ALLOCATION] while holding a [Ptr][Ptr].
355    HostAllocation(Ptr),
356    /// Same as [ExternalMemoryTypeFlags::HOST_MAPPED_FOREIGN_MEMORY][ExternalMemoryTypeFlags::HOST_MAPPED_FOREIGN_MEMORY] while holding a [Ptr][Ptr].
357    HostMappedForeignMemory(Ptr),
358}
359impl ExternalBufferMemory {
360    /// Get the [ExternalMemoryType][ExternalMemoryType] from this enum.
361    pub fn external_memory_type(&self) -> ExternalMemoryType {
362        match self {
363            #[cfg(unix)]
364            Self::OpaqueFd(_) => ExternalMemoryType::OpaqueFd,
365            #[cfg(windows)]
366            Self::OpaqueWin32(_) => ExternalMemoryType::OpaqueWin32,
367            #[cfg(windows)]
368            Self::OpaqueWin32Kmt(_) => ExternalMemoryType::OpaqueWin32Kmt,
369            #[cfg(windows)]
370            Self::D3D11Texture(_) => ExternalMemoryType::D3D11Texture,
371            #[cfg(windows)]
372            Self::D3D11TextureKmt(_) => ExternalMemoryType::D3D11TextureKmt,
373            #[cfg(windows)]
374            Self::D3D12Heap(_) => ExternalMemoryType::D3D12Heap,
375            #[cfg(windows)]
376            Self::D3D12Resource(_) => ExternalMemoryType::D3D12Resource,
377            #[cfg(any(target_os = "linux", target_os = "android"))]
378            Self::DmaBuf(_) => ExternalMemoryType::DmaBuf,
379            #[cfg(target_os = "android")]
380            Self::AndroidHardwareBuffer(_) => ExternalMemoryType::AndroidHardwareBuffer,
381            Self::HostAllocation(_) => ExternalMemoryType::HostAllocation,
382            Self::HostMappedForeignMemory(_) => ExternalMemoryType::HostMappedForeignMemory,
383        }
384    }
385
386    /// Get the [PlatformMemoryType][PlatformMemoryType] from this enum.
387    pub fn platform_memory_type(&self) -> PlatformMemoryType {
388        match self {
389            #[cfg(unix)]
390            Self::OpaqueFd(_) => PlatformMemoryType::Fd,
391            #[cfg(windows)]
392            Self::OpaqueWin32(_) => PlatformMemoryType::Handle,
393            #[cfg(windows)]
394            Self::OpaqueWin32Kmt(_) => PlatformMemoryType::Handle,
395            #[cfg(windows)]
396            Self::D3D11Texture(_) => PlatformMemoryType::Handle,
397            #[cfg(windows)]
398            Self::D3D11TextureKmt(_) => PlatformMemoryType::Handle,
399            #[cfg(windows)]
400            Self::D3D12Heap(_) => PlatformMemoryType::Handle,
401            #[cfg(windows)]
402            Self::D3D12Resource(_) => PlatformMemoryType::Handle,
403            #[cfg(any(target_os = "linux", target_os = "android"))]
404            Self::DmaBuf(_) => PlatformMemoryType::Fd,
405            #[cfg(target_os = "android")]
406            Self::AndroidHardwareBuffer(_) => PlatformMemoryType::Fd,
407            Self::HostAllocation(_) => PlatformMemoryType::Ptr,
408            Self::HostMappedForeignMemory(_) => PlatformMemoryType::Ptr,
409        }
410    }
411
412    #[cfg(unix)]
413    /// Get the associated unix file descriptor as ([Fd][Fd]).
414    pub fn fd(&self) -> Option<&Fd> {
415        match self {
416            Self::OpaqueFd(fd) => Some(fd),
417            #[cfg(any(target_os = "linux", target_os = "android"))]
418            Self::DmaBuf(fd) => Some(fd),
419            #[cfg(target_os = "android")]
420            Self::AndroidHardwareBuffer(fd) => Some(fd),
421            _ => None,
422        }
423    }
424    #[cfg(windows)]
425    /// Get the associated windows handle as ([Handle][Handle]).
426    pub fn handle(&self) -> Option<&Handle> {
427        match self {
428            Self::OpaqueWin32(handle) => Some(handle),
429            Self::OpaqueWin32Kmt(handle) => Some(handle),
430            Self::D3D11Texture(handle) => Some(handle),
431            Self::D3D11TextureKmt(handle) => Some(handle),
432            Self::D3D12Heap(handle) => Some(handle),
433            Self::D3D12Resource(handle) => Some(handle),
434            _ => None,
435        }
436    }
437
438    /// Get the associated host pointer as ([Ptr][Ptr]).
439    pub fn ptr(&self) -> Option<&Ptr> {
440        match self {
441            Self::HostAllocation(ptr) => Some(ptr),
442            Self::HostMappedForeignMemory(ptr) => Some(ptr),
443            // Without this on non unix or windows platform, this will trigger error for unreachable pattern
444            #[allow(unreachable_patterns)]
445            _ => None,
446        }
447    }
448}
449
450/// Representation of an external memory type for buffers.
451pub type ExternalBufferMemoryType = ExternalMemoryType;
452
453
454/// Representation of an external memory for image creation.
455#[derive(Debug)]
456pub enum ExternalImageMemory {
457    #[cfg(unix)]
458    /// This is supported on Unix only.
459    /// Same as [ExternalMemoryTypeFlags::OPAQUE_FD][ExternalMemoryTypeFlags::OPAQUE_FD] while holding a [Fd][Fd].
460    OpaqueFd(Fd),
461    #[cfg(windows)]
462    /// This is supported on Windows only.
463    /// Same as [ExternalMemoryTypeFlags::OPAQUE_WIN32][ExternalMemoryTypeFlags::OPAQUE_WIN32] while holding a [Handle][Handle].
464    OpaqueWin32(Handle),
465    #[cfg(windows)]
466    /// This is supported on Windows only.
467    /// Same as [ExternalMemoryTypeFlags::OPAQUE_WIN32_KMT][ExternalMemoryTypeFlags::OPAQUE_WIN32_KMT] while holding a [Handle][Handle].
468    OpaqueWin32Kmt(Handle),
469    #[cfg(windows)]
470    /// This is supported on Windows only.
471    /// Same as [ExternalMemoryTypeFlags::D3D11_TEXTURE][ExternalMemoryTypeFlags::D3D11_TEXTURE] while holding a [Handle][Handle].
472    D3D11Texture(Handle),
473    #[cfg(windows)]
474    /// This is supported on Windows only.
475    /// Same as [ExternalMemoryTypeFlags::D3D11_TEXTURE_KMT][ExternalMemoryTypeFlags::D3D11_TEXTURE_KMT] while holding a [Handle][Handle].
476    D3D11TextureKmt(Handle),
477    #[cfg(windows)]
478    /// This is supported on Windows only.
479    /// Same as [ExternalMemoryTypeFlags::D3D12_HEAP][ExternalMemoryTypeFlags::D3D12_HEAP] while holding a [Handle][Handle].
480    D3D12Heap(Handle),
481    #[cfg(windows)]
482    /// This is supported on Windows only.
483    /// Same as [ExternalMemoryTypeFlags::D3D12_RESOURCE][ExternalMemoryTypeFlags::D3D12_RESOURCE] while holding a [Handle][Handle].
484    D3D12Resource(Handle),
485    #[cfg(any(target_os = "linux", target_os = "android"))]
486    /// This is supported on Linux or Android only.
487    /// Same as [ExternalMemoryTypeFlags::DMA_BUF][ExternalMemoryTypeFlags::DMA_BUF] while holding a [Fd][Fd].
488    DmaBuf(Fd, Option<DrmFormatImageProperties>),
489    #[cfg(any(target_os = "android"))]
490    /// This is supported on Android only.
491    /// Same as [ExternalMemoryTypeFlags::ANDROID_HARDWARE_BUFFER][ExternalMemoryTypeFlags::ANDROID_HARDWARE_BUFFER] while holding a [Fd][Fd].
492    AndroidHardwareBuffer(Fd),
493    /// Same as [ExternalMemoryTypeFlags::HOST_ALLOCATION][ExternalMemoryTypeFlags::HOST_ALLOCATION] while holding a [Ptr][Ptr].
494    HostAllocation(Ptr),
495    /// Same as [ExternalMemoryTypeFlags::HOST_MAPPED_FOREIGN_MEMORY][ExternalMemoryTypeFlags::HOST_MAPPED_FOREIGN_MEMORY] while holding a [Ptr][Ptr].
496    HostMappedForeignMemory(Ptr),
497}
498impl ExternalImageMemory {
499    /// Get the [ExternalMemoryType][ExternalMemoryType] from this enum.
500    pub fn external_memory_type(&self) -> ExternalMemoryType {
501        match self {
502            #[cfg(unix)]
503            Self::OpaqueFd(_) => ExternalMemoryType::OpaqueFd,
504            #[cfg(windows)]
505            Self::OpaqueWin32(_) => ExternalMemoryType::OpaqueWin32,
506            #[cfg(windows)]
507            Self::OpaqueWin32Kmt(_) => ExternalMemoryType::OpaqueWin32Kmt,
508            #[cfg(windows)]
509            Self::D3D11Texture(_) => ExternalMemoryType::D3D11Texture,
510            #[cfg(windows)]
511            Self::D3D11TextureKmt(_) => ExternalMemoryType::D3D11TextureKmt,
512            #[cfg(windows)]
513            Self::D3D12Heap(_) => ExternalMemoryType::D3D12Heap,
514            #[cfg(windows)]
515            Self::D3D12Resource(_) => ExternalMemoryType::D3D12Resource,
516            #[cfg(any(target_os = "linux", target_os = "android"))]
517            Self::DmaBuf(_, _) => ExternalMemoryType::DmaBuf,
518            #[cfg(target_os = "android")]
519            Self::AndroidHardwareBuffer(_) => ExternalMemoryType::AndroidHardwareBuffer,
520            Self::HostAllocation(_) => ExternalMemoryType::HostAllocation,
521            Self::HostMappedForeignMemory(_) => ExternalMemoryType::HostMappedForeignMemory,
522        }
523    }
524
525    /// Get the [PlatformMemoryType][PlatformMemoryType] from this enum.
526    pub fn platform_memory_type(&self) -> PlatformMemoryType {
527        match self {
528            #[cfg(unix)]
529            Self::OpaqueFd(_) => PlatformMemoryType::Fd,
530            #[cfg(windows)]
531            Self::OpaqueWin32(_) => PlatformMemoryType::Handle,
532            #[cfg(windows)]
533            Self::OpaqueWin32Kmt(_) => PlatformMemoryType::Handle,
534            #[cfg(windows)]
535            Self::D3D11Texture(_) => PlatformMemoryType::Handle,
536            #[cfg(windows)]
537            Self::D3D11TextureKmt(_) => PlatformMemoryType::Handle,
538            #[cfg(windows)]
539            Self::D3D12Heap(_) => PlatformMemoryType::Handle,
540            #[cfg(windows)]
541            Self::D3D12Resource(_) => PlatformMemoryType::Handle,
542            #[cfg(any(target_os = "linux", target_os = "android"))]
543            Self::DmaBuf(_, _) => PlatformMemoryType::Fd,
544            #[cfg(target_os = "android")]
545            Self::AndroidHardwareBuffer(_) => PlatformMemoryType::Fd,
546            Self::HostAllocation(_) => PlatformMemoryType::Ptr,
547            Self::HostMappedForeignMemory(_) => PlatformMemoryType::Ptr,
548        }
549    }
550
551    #[cfg(unix)]
552    /// Get the associated unix file descriptor as ([Fd][Fd]).
553    pub fn fd(&self) -> Option<&Fd> {
554        match self {
555            Self::OpaqueFd(fd) => Some(fd),
556            #[cfg(any(target_os = "linux", target_os = "android"))]
557            Self::DmaBuf(fd, _drm_format_properties) => Some(fd),
558            #[cfg(target_os = "android")]
559            Self::AndroidHardwareBuffer(fd) => Some(fd),
560            _ => None,
561        }
562    }
563
564    #[cfg(windows)]
565    /// Get the associated windows handle as ([Handle][Handle]).
566    pub fn handle(&self) -> Option<&Handle> {
567        match self {
568            Self::OpaqueWin32(handle) => Some(handle),
569            Self::OpaqueWin32Kmt(handle) => Some(handle),
570            Self::D3D11Texture(handle) => Some(handle),
571            Self::D3D11TextureKmt(handle) => Some(handle),
572            Self::D3D12Heap(handle) => Some(handle),
573            Self::D3D12Resource(handle) => Some(handle),
574            _ => None,
575        }
576    }
577
578    /// Get the associated host pointer as ([Ptr][Ptr]).
579    pub fn ptr(&self) -> Option<&Ptr> {
580        match self {
581            Self::HostAllocation(ptr) => Some(ptr),
582            Self::HostMappedForeignMemory(ptr) => Some(ptr),
583            // Without this on non unix or windows platform, this will trigger error for unreachable pattern
584            #[allow(unreachable_patterns)]
585            _ => None,
586        }
587    }
588}
589
590
591/// Representation of an external memory type for images.
592#[derive(Clone, Debug, PartialEq)]
593pub enum ExternalImageMemoryType {
594    #[cfg(any(unix, doc))]
595    /// This is supported on Unix only.
596    /// Same as [ExternalMemoryTypeFlags::OPAQUE_FD][ExternalMemoryTypeFlags::OPAQUE_FD]
597    OpaqueFd,
598    #[cfg(any(windows, doc))]
599    /// This is supported on Windows only.
600    /// Same as [ExternalMemoryTypeFlags::OPAQUE_WIN32][ExternalMemoryTypeFlags::OPAQUE_WIN32]
601    OpaqueWin32,
602    #[cfg(any(windows, doc))]
603    /// This is supported on Windows only.
604    /// Same as [ExternalMemoryTypeFlags::OPAQUE_WIN32_KMT][ExternalMemoryTypeFlags::OPAQUE_WIN32_KMT]
605    OpaqueWin32Kmt,
606    #[cfg(any(windows, doc))]
607    /// This is supported on Windows only.
608    /// Same as [ExternalMemoryTypeFlags::D3D11_TEXTURE][ExternalMemoryTypeFlags::D3D11_TEXTURE]
609    D3D11Texture,
610    #[cfg(any(windows, doc))]
611    /// This is supported on Windows only.
612    /// Same as [ExternalMemoryTypeFlags::D3D11_TEXTURE_KMT][ExternalMemoryTypeFlags::D3D11_TEXTURE_KMT]
613    D3D11TextureKmt,
614    #[cfg(any(windows, doc))]
615    /// This is supported on Windows only.
616    /// Same as [ExternalMemoryTypeFlags::D3D12_HEAP][ExternalMemoryTypeFlags::D3D12_HEAP]
617    D3D12Heap,
618    #[cfg(any(windows, doc))]
619    /// This is supported on Windows only.
620    /// Same as [ExternalMemoryTypeFlags::D3D12_RESOURCE][ExternalMemoryTypeFlags::D3D12_RESOURCE]
621    D3D12Resource,
622    #[cfg(any(target_os = "linux", target_os = "android", doc))]
623    /// This is supported on Linux or Android only.
624    /// Same as [ExternalMemoryTypeFlags::DMA_BUF][ExternalMemoryTypeFlags::DMA_BUF]
625    DmaBuf(Vec<DrmModifier>),
626    #[cfg(any(target_os = "android", doc))]
627    /// This is supported on Android only.
628    /// Same as [ExternalMemoryTypeFlags::ANDROID_HARDWARE_BUFFER][ExternalMemoryTypeFlags::ANDROID_HARDWARE_BUFFER]
629    AndroidHardwareBuffer,
630    /// Same as [ExternalMemoryTypeFlags::HOST_ALLOCATION][ExternalMemoryTypeFlags::HOST_ALLOCATION]
631    HostAllocation,
632    /// Same as [ExternalMemoryTypeFlags::HOST_MAPPED_FOREIGN_MEMORY][ExternalMemoryTypeFlags::HOST_MAPPED_FOREIGN_MEMORY]
633    HostMappedForeignMemory,
634}
635impl ExternalImageMemoryType {
636    /// Get the [ExternalMemoryType][ExternalMemoryType] from this enum.
637    pub fn external_memory_type(&self) -> ExternalMemoryType {
638        match self {
639            #[cfg(unix)]
640            Self::OpaqueFd => ExternalMemoryType::OpaqueFd,
641            #[cfg(windows)]
642            Self::OpaqueWin32 => ExternalMemoryType::OpaqueWin32,
643            #[cfg(windows)]
644            Self::OpaqueWin32Kmt => ExternalMemoryType::OpaqueWin32Kmt,
645            #[cfg(windows)]
646            Self::D3D11Texture => ExternalMemoryType::D3D11Texture,
647            #[cfg(windows)]
648            Self::D3D11TextureKmt => ExternalMemoryType::D3D11TextureKmt,
649            #[cfg(windows)]
650            Self::D3D12Heap => ExternalMemoryType::D3D12Heap,
651            #[cfg(windows)]
652            Self::D3D12Resource => ExternalMemoryType::D3D12Resource,
653            #[cfg(any(target_os = "linux", target_os = "android"))]
654            Self::DmaBuf(_) => ExternalMemoryType::DmaBuf,
655            #[cfg(target_os = "android")]
656            Self::AndroidHardwareBuffer => ExternalMemoryType::AndroidHardwareBuffer,
657            Self::HostAllocation => ExternalMemoryType::HostAllocation,
658            Self::HostMappedForeignMemory => ExternalMemoryType::HostMappedForeignMemory,
659        }
660    }
661}
662
663type Offset = u64;
664
665/// Footprint of a plane layout in memory.
666#[derive(Debug, Clone, PartialEq, Eq, Hash)]
667#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
668pub struct PlaneLayout {
669    /// Byte slice occupied by the subresource.
670    pub slice: Range<Offset>,
671    /// Byte distance between rows.
672    pub row_pitch: Offset,
673    /// Byte distance between array layers.
674    pub array_pitch: Offset,
675    /// Byte distance between depth slices.
676    pub depth_pitch: Offset,
677}
678
679/// Description of drm format properties used to create an image using drm format modifier.
680#[derive(Debug, Clone, PartialEq, Eq, Hash)]
681pub struct DrmFormatImageProperties {
682    /// Drm format modifier
683    pub drm_modifier: DrmModifier,
684    /// Plane subresource layouts
685    pub plane_layouts: Vec<PlaneLayout>,
686}
external_memory/lib.rs

external_memory/
lib.rs
