gfx_core/
memory.rs

1// Copyright 2016 The Gfx-rs Developers.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! Types to describe the properties of memory allocated for gfx resources.
16
17use std::mem;
18
19// TODO: It would be useful to document what parameters these map to in D3D, vulkan, etc.
20
21/// How this memory will be used regarding GPU-CPU data flow.
22///
23/// This information is used to create resources
24/// (see [gfx::Factory](../trait.Factory.html#overview)).
25#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
26#[cfg_attr(feature = "serialize", derive(Serialize, Deserialize))]
27#[repr(u8)]
28pub enum Usage {
29    /// Full speed GPU access.
30    /// Optimal for render targets and resourced memory.
31    Data,
32    /// CPU to GPU data flow with update commands.
33    /// Used for dynamic buffer data, typically constant buffers.
34    Dynamic,
35    /// CPU to GPU data flow with mapping.
36    /// Used for staging for upload to GPU.
37    Upload,
38    /// GPU to CPU data flow with mapping.
39    /// Used for staging for download from GPU.
40    Download,
41}
42
43bitflags!(
44    /// Flags providing information about the type of memory access to a resource.
45    ///
46    /// An `Access` value can be a combination of the the following bit patterns:
47    ///
48    /// - [`READ`](constant.READ.html)
49    /// - [`WRITE`](constant.WRITE.html)
50    /// - Or [`RW`](constant.RW.html) which is equivalent to `READ` and `WRITE`.
51    ///
52    /// This information is used to create resources
53    /// (see [gfx::Factory](trait.Factory.html#overview)).
54    #[cfg_attr(feature = "serialize", derive(Serialize, Deserialize))]
55    pub struct Access: u8 {
56        /// Read access
57        const READ  = 0x1;
58        /// Write access
59        const WRITE = 0x2;
60        /// Full access
61        const RW    = 0x3;
62    }
63);
64
65bitflags!(
66    /// Flags providing information about the usage of a resource.
67    ///
68    /// A `Bind` value can be a combination of the following bit patterns:
69    ///
70    /// - [`RENDER_TARGET`](constant.RENDER_TARGET.html)
71    /// - [`DEPTH_STENCIL`](constant.DEPTH_STENCIL.html)
72    /// - [`SHADER_RESOURCE`](constant.SHADER_RESOURCE.html)
73    /// - [`UNORDERED_ACCESS`](constant.UNORDERED_ACCESS.html)
74    /// - [`TRANSFER_SRC`](constant.TRANSFER_SRC.html)
75    /// - [`TRANSFER_DST`](constant.TRANSFER_DST.html)
76    ///
77    ///
78    /// This information is used to create resources
79    /// (see [gfx::Factory](trait.Factory.html#overview)).
80    #[cfg_attr(feature = "serialize", derive(Serialize, Deserialize))]
81    pub struct Bind: u8 {
82        /// Can be rendered into.
83        const RENDER_TARGET    = 0x1;
84        /// Can serve as a depth/stencil target.
85        const DEPTH_STENCIL    = 0x2;
86        /// Can be bound to the shader for reading.
87        const SHADER_RESOURCE  = 0x4;
88        /// Can be bound to the shader for writing.
89        const UNORDERED_ACCESS = 0x8;
90        /// Can be transfered from.
91        const TRANSFER_SRC     = 0x10;
92        /// Can be transfered into.
93        const TRANSFER_DST     = 0x20;
94    }
95);
96
97impl Bind {
98    /// Is this memory bound to be mutated ?
99    pub fn is_mutable(&self) -> bool {
100        let mutable = Self::TRANSFER_DST | Self::UNORDERED_ACCESS |
101                      Self::RENDER_TARGET | Self::DEPTH_STENCIL;
102        self.intersects(mutable)
103    }
104}
105
106/// A service trait used to get the raw data out of strong types.
107/// Not meant for public use.
108#[doc(hidden)]
109pub trait Typed: Sized {
110    /// The raw type behind the phantom.
111    type Raw;
112    /// Crete a new phantom from the raw type.
113    fn new(raw: Self::Raw) -> Self;
114    /// Get an internal reference to the raw type.
115    fn raw(&self) -> &Self::Raw;
116}
117
118/// A trait for plain-old-data types.
119///
120/// A POD type does not have invalid bit patterns and can be safely
121/// created from arbitrary bit pattern.
122/// The `Pod` trait is implemented for standard integer and floating point numbers as well as
123/// common arrays of them (for example `[f32; 2]`).
124pub unsafe trait Pod {}
125
126macro_rules! impl_pod {
127    ( ty = $($ty:ty)* ) => { $( unsafe impl Pod for $ty {} )* };
128    ( ar = $($tt:expr)* ) => { $( unsafe impl<T: Pod> Pod for [T; $tt] {} )* };
129}
130
131impl_pod! { ty = isize usize i8 u8 i16 u16 i32 u32 i64 u64 f32 f64 }
132impl_pod! { ar =
133    0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
134}
135
136unsafe impl<T: Pod, U: Pod> Pod for (T, U) {}
137
138/// Cast a slice from one POD type to another.
139pub fn cast_slice<A: Pod, B: Pod>(slice: &[A]) -> &[B] {
140    use std::slice;
141
142    let raw_len = mem::size_of::<A>().wrapping_mul(slice.len());
143    let len = raw_len / mem::size_of::<B>();
144    assert_eq!(raw_len, mem::size_of::<B>().wrapping_mul(len));
145    unsafe {
146        slice::from_raw_parts(slice.as_ptr() as *const B, len)
147    }
148}
gfx_core/memory.rs

gfx_core/
memory.rs
