Point Cloud Library (PCL)  1.14.0-dev
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 #include <atomic>
43 
44 namespace pcl {
45 namespace gpu {
46 ///////////////////////////////////////////////////////////////////////////////
47 /** \brief @b DeviceMemory class
48  *
49  * \note This is a BLOB container class with reference counting for GPU memory.
50  *
51  * \author Anatoly Baksheev
52  */
53 
55 public:
56  /** \brief Empty constructor. */
58 
59  /** \brief Destructor. */
61 
62  /** \brief Allocates internal buffer in GPU memory
63  * \param sizeBytes_arg amount of memory to allocate
64  * */
65  DeviceMemory(std::size_t sizeBytes_arg);
66 
67  /** \brief Initializes with user allocated buffer. Reference counting is disabled in
68  * this case.
69  * \param ptr_arg pointer to buffer
70  * \param sizeBytes_arg buffer size
71  * */
72  DeviceMemory(void* ptr_arg, std::size_t sizeBytes_arg);
73 
74  /** \brief Copy constructor. Just increments reference counter. */
75  DeviceMemory(const DeviceMemory& other_arg);
76 
77  /** \brief Assignment operator. Just increments reference counter. */
79  operator=(const DeviceMemory& other_arg);
80 
81  /** \brief Allocates internal buffer in GPU memory. If internal buffer was created
82  * before the function recreates it with new size. If new and old sizes are equal it
83  * does nothing.
84  * \param sizeBytes_arg buffer size
85  * */
86  void
87  create(std::size_t sizeBytes_arg);
88 
89  /** \brief Decrements reference counter and releases internal buffer if needed. */
90  void
92 
93  /** \brief Performs data copying. If destination size differs it will be reallocated.
94  * \param other destination container
95  * */
96  void
97  copyTo(DeviceMemory& other) const;
98 
99  /** \brief Uploads data to internal buffer in GPU memory. It calls create() inside to
100  * ensure that internal buffer size is enough.
101  * \param host_ptr_arg pointer to buffer to upload
102  * \param sizeBytes_arg buffer size
103  * */
104  void
105  upload(const void* host_ptr_arg, std::size_t sizeBytes_arg);
106 
107  /** \brief Uploads data from CPU memory to device array.
108  * \note This overload never allocates memory in contrast to the
109  * other upload function.
110  * \return true if upload successful
111  * \param host_ptr_arg pointer to buffer to upload
112  * \param device_begin_byte_offset first byte position to upload to
113  * \param num_bytes number of bytes to upload
114  * */
115  bool
116  upload(const void* host_ptr_arg,
117  std::size_t device_begin_byte_offset,
118  std::size_t num_bytes);
119 
120  /** \brief Downloads data from internal buffer to CPU memory
121  * \param host_ptr_arg pointer to buffer to download
122  * */
123  void
124  download(void* host_ptr_arg) const;
125 
126  /** \brief Downloads data from internal buffer to CPU memory.
127  * \return true if download successful
128  * \param host_ptr_arg pointer to buffer to download
129  * \param device_begin_byte_offset first byte position to download
130  * \param num_bytes number of bytes to download
131  * */
132  bool
133  download(void* host_ptr_arg,
134  std::size_t device_begin_byte_offset,
135  std::size_t num_bytes) const;
136 
137  /** \brief Performs swap of data pointed with another device memory.
138  * \param other_arg device memory to swap with
139  * */
140  void
141  swap(DeviceMemory& other_arg);
142 
143  /** \brief Returns pointer for internal buffer in GPU memory. */
144  template <class T>
145  T*
146  ptr();
147 
148  /** \brief Returns constant pointer for internal buffer in GPU memory. */
149  template <class T>
150  const T*
151  ptr() const;
152 
153  /** \brief Conversion to PtrSz for passing to kernel functions. */
154  template <class U>
155  operator PtrSz<U>() const;
156 
157  /** \brief Returns true if unallocated otherwise false. */
158  bool
159  empty() const;
160 
161  std::size_t
162  sizeBytes() const;
163 
164 private:
165  /** \brief Device pointer. */
166  void* data_;
167 
168  /** \brief Allocated size in bytes. */
169  std::size_t sizeBytes_;
170 
171  /** \brief Pointer to reference counter in CPU memory. */
172  std::atomic<int>* refcount_;
173 };
174 
175 ///////////////////////////////////////////////////////////////////////////////
176 /** \brief @b DeviceMemory2D class
177  *
178  * \note This is a BLOB container class with reference counting for pitched GPU memory.
179  *
180  * \author Anatoly Baksheev
181  */
182 
184 public:
185  /** \brief Empty constructor. */
187 
188  /** \brief Destructor. */
190 
191  /** \brief Allocates internal buffer in GPU memory
192  * \param rows_arg number of rows to allocate
193  * \param colsBytes_arg width of the buffer in bytes
194  * */
195  DeviceMemory2D(int rows_arg, int colsBytes_arg);
196 
197  /** \brief Initializes with user allocated buffer. Reference counting is disabled in
198  * this case.
199  * \param rows_arg number of rows
200  * \param colsBytes_arg width of the buffer in bytes
201  * \param data_arg pointer to buffer
202  * \param step_arg stride between two consecutive rows in bytes
203  * */
204  DeviceMemory2D(int rows_arg, int colsBytes_arg, void* data_arg, std::size_t step_arg);
205 
206  /** \brief Copy constructor. Just increments reference counter. */
207  DeviceMemory2D(const DeviceMemory2D& other_arg);
208 
209  /** \brief Assignment operator. Just increments reference counter. */
211  operator=(const DeviceMemory2D& other_arg);
212 
213  /** \brief Allocates internal buffer in GPU memory. If internal buffer was created
214  * before the function recreates it with new size. If new and old sizes are equal it
215  * does nothing.
216  * \param rows_arg number of rows to allocate
217  * \param colsBytes_arg width of the buffer in bytes
218  * */
219  void
220  create(int rows_arg, int colsBytes_arg);
221 
222  /** \brief Decrements reference counter and releases internal buffer if needed. */
223  void
225 
226  /** \brief Performs data copying. If destination size differs it will be reallocated.
227  * \param other destination container
228  * */
229  void
230  copyTo(DeviceMemory2D& other) const;
231 
232  /** \brief Uploads data to internal buffer in GPU memory. It calls create() inside to
233  * ensure that internal buffer size is enough.
234  * \param host_ptr_arg pointer to host buffer to upload
235  * \param host_step_arg stride between two consecutive rows in bytes for host buffer
236  * \param rows_arg number of rows to upload
237  * \param colsBytes_arg width of host buffer in bytes
238  * */
239  void
240  upload(const void* host_ptr_arg,
241  std::size_t host_step_arg,
242  int rows_arg,
243  int colsBytes_arg);
244 
245  /** \brief Downloads data from internal buffer to CPU memory. User is responsible for
246  * correct host buffer size.
247  * \param host_ptr_arg pointer to host buffer to download
248  * \param host_step_arg stride between two consecutive rows in bytes for host buffer
249  * */
250  void
251  download(void* host_ptr_arg, std::size_t host_step_arg) const;
252 
253  /** \brief Performs swap of data pointed with another device memory.
254  * \param other_arg device memory to swap with
255  * */
256  void
257  swap(DeviceMemory2D& other_arg);
258 
259  /** \brief Returns pointer to given row in internal buffer.
260  * \param y_arg row index
261  * */
262  template <class T>
263  T*
264  ptr(int y_arg = 0);
265 
266  /** \brief Returns constant pointer to given row in internal buffer.
267  * \param y_arg row index
268  * */
269  template <class T>
270  const T*
271  ptr(int y_arg = 0) const;
272 
273  /** \brief Conversion to PtrStep for passing to kernel functions. */
274  template <class U>
275  operator PtrStep<U>() const;
276 
277  /** \brief Conversion to PtrStepSz for passing to kernel functions. */
278  template <class U>
279  operator PtrStepSz<U>() const;
280 
281  /** \brief Returns true if unallocated otherwise false. */
282  bool
283  empty() const;
284 
285  /** \brief Returns number of bytes in each row. */
286  int
287  colsBytes() const;
288 
289  /** \brief Returns number of rows. */
290  int
291  rows() const;
292 
293  /** \brief Returns stride between two consecutive rows in bytes for internal buffer.
294  * Step is stored always and everywhere in bytes!!! */
295  std::size_t
296  step() const;
297 
298 private:
299  /** \brief Device pointer. */
300  void* data_;
301 
302  /** \brief Stride between two consecutive rows in bytes for internal buffer. Step is
303  * stored always and everywhere in bytes!!! */
304  std::size_t step_;
305 
306  /** \brief Width of the buffer in bytes. */
307  int colsBytes_;
308 
309  /** \brief Number of rows. */
310  int rows_;
311 
312  /** \brief Pointer to reference counter in CPU memory. */
313  std::atomic<int>* refcount_;
314 };
315 } // namespace gpu
316 
317 namespace device {
320 } // namespace device
321 } // namespace pcl
322 
323 #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:54
bool upload(const void *host_ptr_arg, std::size_t device_begin_byte_offset, std::size_t num_bytes)
Uploads data from CPU memory to device array.
DeviceMemory()
Empty constructor.
DeviceMemory(std::size_t sizeBytes_arg)
Allocates internal buffer in GPU memory.
std::size_t sizeBytes() const
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 download(void *host_ptr_arg, std::size_t device_begin_byte_offset, std::size_t num_bytes) const
Downloads data from internal buffer to CPU memory.
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