Point Cloud Library (PCL)  1.12.0
device_memory.h
1 /*
2  * Software License Agreement (BSD License)
3  *
4  * Copyright (c) 2011, Willow Garage, Inc.
5  * All rights reserved.
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions
9  * are met:
10  *
11  * * Redistributions of source code must retain the above copyright
12  * notice, this list of conditions and the following disclaimer.
13  * * Redistributions in binary form must reproduce the above
14  * copyright notice, this list of conditions and the following
15  * disclaimer in the documentation and/or other materials provided
16  * with the distribution.
17  * * Neither the name of Willow Garage, Inc. nor the names of its
18  * contributors may be used to endorse or promote products derived
19  * from this software without specific prior written permission.
20  *
21  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
24  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
25  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
26  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
27  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
28  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
29  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
31  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
32  * POSSIBILITY OF SUCH DAMAGE.
33  *
34  * Author: Anatoly Baskeheev, Itseez Ltd, (myname.mysurname@mycompany.com)
35  */
36 
37 #pragma once
38 
39 #include <pcl/gpu/containers/kernel_containers.h>
40 #include <pcl/pcl_exports.h>
41 
42 namespace pcl {
43 namespace gpu {
44 ///////////////////////////////////////////////////////////////////////////////
45 /** \brief @b DeviceMemory class
46  *
47  * \note This is a BLOB container class with reference counting for GPU memory.
48  *
49  * \author Anatoly Baksheev
50  */
51 
53 public:
54  /** \brief Empty constructor. */
56 
57  /** \brief Destructor. */
59 
60  /** \brief Allocates internal buffer in GPU memory
61  * \param sizeBytes_arg amount of memory to allocate
62  * */
63  DeviceMemory(std::size_t sizeBytes_arg);
64 
65  /** \brief Initializes with user allocated buffer. Reference counting is disabled in
66  * this case.
67  * \param ptr_arg pointer to buffer
68  * \param sizeBytes_arg buffer size
69  * */
70  DeviceMemory(void* ptr_arg, std::size_t sizeBytes_arg);
71 
72  /** \brief Copy constructor. Just increments reference counter. */
73  DeviceMemory(const DeviceMemory& other_arg);
74 
75  /** \brief Assignment operator. Just increments reference counter. */
77  operator=(const DeviceMemory& other_arg);
78 
79  /** \brief Allocates internal buffer in GPU memory. If internal buffer was created
80  * before the function recreates it with new size. If new and old sizes are equal it
81  * does nothing.
82  * \param sizeBytes_arg buffer size
83  * */
84  void
85  create(std::size_t sizeBytes_arg);
86 
87  /** \brief Decrements reference counter and releases internal buffer if needed. */
88  void
90 
91  /** \brief Performs data copying. If destination size differs it will be reallocated.
92  * \param other destination container
93  * */
94  void
95  copyTo(DeviceMemory& other) const;
96 
97  /** \brief Uploads data to internal buffer in GPU memory. It calls create() inside to
98  * ensure that intenal buffer size is enough.
99  * \param host_ptr_arg pointer to buffer to upload
100  * \param sizeBytes_arg buffer size
101  * */
102  void
103  upload(const void* host_ptr_arg, std::size_t sizeBytes_arg);
104 
105  /** \brief Uploads data from CPU memory to device array.
106  * \note This overload never allocates memory in contrast to the
107  * other upload function.
108  * \return true if upload successful
109  * \param host_ptr_arg pointer to buffer to upload
110  * \param device_begin_byte_offset first byte position to upload to
111  * \param num_bytes number of bytes to upload
112  * */
113  bool
114  upload(const void* host_ptr,
115  std::size_t device_begin_byte_offset,
116  std::size_t num_bytes);
117 
118  /** \brief Downloads data from internal buffer to CPU memory
119  * \param host_ptr_arg pointer to buffer to download
120  * */
121  void
122  download(void* host_ptr_arg) const;
123 
124  /** \brief Downloads data from internal buffer to CPU memory.
125  * \return true if download successful
126  * \param host_ptr_arg pointer to buffer to download
127  * \param device_begin_byte_offset first byte position to download
128  * \param num_bytes number of bytes to download
129  * */
130  bool
131  download(void* host_ptr,
132  std::size_t device_begin_byte_offset,
133  std::size_t num_bytes) const;
134 
135  /** \brief Performs swap of data pointed with another device memory.
136  * \param other_arg device memory to swap with
137  * */
138  void
139  swap(DeviceMemory& other_arg);
140 
141  /** \brief Returns pointer for internal buffer in GPU memory. */
142  template <class T>
143  T*
144  ptr();
145 
146  /** \brief Returns constant pointer for internal buffer in GPU memory. */
147  template <class T>
148  const T*
149  ptr() const;
150 
151  /** \brief Conversion to PtrSz for passing to kernel functions. */
152  template <class U>
153  operator PtrSz<U>() const;
154 
155  /** \brief Returns true if unallocated otherwise false. */
156  bool
157  empty() const;
158 
159  std::size_t
160  sizeBytes() const;
161 
162 private:
163  /** \brief Device pointer. */
164  void* data_;
165 
166  /** \brief Allocated size in bytes. */
167  std::size_t sizeBytes_;
168 
169  /** \brief Pointer to reference counter in CPU memory. */
170  int* refcount_;
171 };
172 
173 ///////////////////////////////////////////////////////////////////////////////
174 /** \brief @b DeviceMemory2D class
175  *
176  * \note This is a BLOB container class with reference counting for pitched GPU memory.
177  *
178  * \author Anatoly Baksheev
179  */
180 
182 public:
183  /** \brief Empty constructor. */
185 
186  /** \brief Destructor. */
188 
189  /** \brief Allocates internal buffer in GPU memory
190  * \param rows_arg number of rows to allocate
191  * \param colsBytes_arg width of the buffer in bytes
192  * */
193  DeviceMemory2D(int rows_arg, int colsBytes_arg);
194 
195  /** \brief Initializes with user allocated buffer. Reference counting is disabled in
196  * this case.
197  * \param rows_arg number of rows
198  * \param colsBytes_arg width of the buffer in bytes
199  * \param data_arg pointer to buffer
200  * \param step_arg stride between two consecutive rows in bytes
201  * */
202  DeviceMemory2D(int rows_arg, int colsBytes_arg, void* data_arg, std::size_t step_arg);
203 
204  /** \brief Copy constructor. Just increments reference counter. */
205  DeviceMemory2D(const DeviceMemory2D& other_arg);
206 
207  /** \brief Assignment operator. Just increments reference counter. */
209  operator=(const DeviceMemory2D& other_arg);
210 
211  /** \brief Allocates internal buffer in GPU memory. If internal buffer was created
212  * before the function recreates it with new size. If new and old sizes are equal it
213  * does nothing.
214  * \param rows_arg number of rows to allocate
215  * \param colsBytes_arg width of the buffer in bytes
216  * */
217  void
218  create(int rows_arg, int colsBytes_arg);
219 
220  /** \brief Decrements reference counter and releases internal buffer if needed. */
221  void
223 
224  /** \brief Performs data copying. If destination size differs it will be reallocated.
225  * \param other destination container
226  * */
227  void
228  copyTo(DeviceMemory2D& other) const;
229 
230  /** \brief Uploads data to internal buffer in GPU memory. It calls create() inside to
231  * ensure that intenal buffer size is enough.
232  * \param host_ptr_arg pointer to host buffer to upload
233  * \param host_step_arg stride between two consecutive rows in bytes for host buffer
234  * \param rows_arg number of rows to upload
235  * \param colsBytes_arg width of host buffer in bytes
236  * */
237  void
238  upload(const void* host_ptr_arg,
239  std::size_t host_step_arg,
240  int rows_arg,
241  int colsBytes_arg);
242 
243  /** \brief Downloads data from internal buffer to CPU memory. User is responsible for
244  * correct host buffer size.
245  * \param host_ptr_arg pointer to host buffer to download
246  * \param host_step_arg stride between two consecutive rows in bytes for host buffer
247  * */
248  void
249  download(void* host_ptr_arg, std::size_t host_step_arg) const;
250 
251  /** \brief Performs swap of data pointed with another device memory.
252  * \param other_arg device memory to swap with
253  * */
254  void
255  swap(DeviceMemory2D& other_arg);
256 
257  /** \brief Returns pointer to given row in internal buffer.
258  * \param y_arg row index
259  * */
260  template <class T>
261  T*
262  ptr(int y_arg = 0);
263 
264  /** \brief Returns constant pointer to given row in internal buffer.
265  * \param y_arg row index
266  * */
267  template <class T>
268  const T*
269  ptr(int y_arg = 0) const;
270 
271  /** \brief Conversion to PtrStep for passing to kernel functions. */
272  template <class U>
273  operator PtrStep<U>() const;
274 
275  /** \brief Conversion to PtrStepSz for passing to kernel functions. */
276  template <class U>
277  operator PtrStepSz<U>() const;
278 
279  /** \brief Returns true if unallocated otherwise false. */
280  bool
281  empty() const;
282 
283  /** \brief Returns number of bytes in each row. */
284  int
285  colsBytes() const;
286 
287  /** \brief Returns number of rows. */
288  int
289  rows() const;
290 
291  /** \brief Returns stride between two consecutive rows in bytes for internal buffer.
292  * Step is stored always and everywhere in bytes!!! */
293  std::size_t
294  step() const;
295 
296 private:
297  /** \brief Device pointer. */
298  void* data_;
299 
300  /** \brief Stride between two consecutive rows in bytes for internal buffer. Step is
301  * stored always and everywhere in bytes!!! */
302  std::size_t step_;
303 
304  /** \brief Width of the buffer in bytes. */
305  int colsBytes_;
306 
307  /** \brief Number of rows. */
308  int rows_;
309 
310  /** \brief Pointer to reference counter in CPU memory. */
311  int* refcount_;
312 };
313 } // namespace gpu
314 
315 namespace device {
318 } // namespace device
319 } // namespace pcl
320 
321 #include <pcl/gpu/containers/impl/device_memory.hpp>
DeviceMemory2D class
bool empty() const
Returns true if unallocated otherwise false.
void swap(DeviceMemory2D &other_arg)
Performs swap of data pointed with another device memory.
std::size_t step() const
Returns stride between two consecutive rows in bytes for internal buffer.
~DeviceMemory2D()
Destructor.
void download(void *host_ptr_arg, std::size_t host_step_arg) const
Downloads data from internal buffer to CPU memory.
void create(int rows_arg, int colsBytes_arg)
Allocates internal buffer in GPU memory.
DeviceMemory2D(int rows_arg, int colsBytes_arg)
Allocates internal buffer in GPU memory.
int colsBytes() const
Returns number of bytes in each row.
int rows() const
Returns number of rows.
void upload(const void *host_ptr_arg, std::size_t host_step_arg, int rows_arg, int colsBytes_arg)
Uploads data to internal buffer in GPU memory.
DeviceMemory2D(int rows_arg, int colsBytes_arg, void *data_arg, std::size_t step_arg)
Initializes with user allocated buffer.
DeviceMemory2D & operator=(const DeviceMemory2D &other_arg)
Assignment operator.
DeviceMemory2D(const DeviceMemory2D &other_arg)
Copy constructor.
void release()
Decrements reference counter and releases internal buffer if needed.
DeviceMemory2D()
Empty constructor.
void copyTo(DeviceMemory2D &other) const
Performs data copying.
DeviceMemory class
Definition: device_memory.h:52
DeviceMemory()
Empty constructor.
DeviceMemory(std::size_t sizeBytes_arg)
Allocates internal buffer in GPU memory.
std::size_t sizeBytes() const
bool download(void *host_ptr, std::size_t device_begin_byte_offset, std::size_t num_bytes) const
Downloads data from internal buffer to CPU memory.
DeviceMemory(void *ptr_arg, std::size_t sizeBytes_arg)
Initializes with user allocated buffer.
void swap(DeviceMemory &other_arg)
Performs swap of data pointed with another device memory.
DeviceMemory(const DeviceMemory &other_arg)
Copy constructor.
bool upload(const void *host_ptr, std::size_t device_begin_byte_offset, std::size_t num_bytes)
Uploads data from CPU memory to device array.
DeviceMemory & operator=(const DeviceMemory &other_arg)
Assignment operator.
void copyTo(DeviceMemory &other) const
Performs data copying.
~DeviceMemory()
Destructor.
void release()
Decrements reference counter and releases internal buffer if needed.
void download(void *host_ptr_arg) const
Downloads data from internal buffer to CPU memory.
bool empty() const
Returns true if unallocated otherwise false.
void upload(const void *host_ptr_arg, std::size_t sizeBytes_arg)
Uploads data to internal buffer in GPU memory.
void create(std::size_t sizeBytes_arg)
Allocates internal buffer in GPU memory.
#define PCL_EXPORTS
Definition: pcl_macros.h:323