Point Cloud Library (PCL)  1.14.1-dev
device_array.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/device_memory.h>
40 #include <pcl/pcl_exports.h>
41 
42 #include <vector>
43 
44 namespace pcl {
45 namespace gpu {
46 //////////////////////////////////////////////////////////////////////////////
47 /** \brief @b DeviceArray class
48  *
49  * \note Typed container for GPU memory with reference counting.
50  *
51  * \author Anatoly Baksheev
52  */
53 template <class T>
55 public:
56  /** \brief Element type. */
57  using type = T;
58 
59  /** \brief Element size. */
60  enum { elem_size = sizeof(T) };
61 
62  /** \brief Empty constructor. */
63  DeviceArray();
64 
65  /** \brief Allocates internal buffer in GPU memory
66  * \param size number of elements to allocate
67  * */
68  DeviceArray(std::size_t size);
69 
70  /** \brief Initializes with user allocated buffer. Reference counting is disabled in
71  * this case.
72  * \param ptr pointer to buffer
73  * \param size elements number
74  * */
75  DeviceArray(T* ptr, std::size_t size);
76 
77  /** \brief Copy constructor. Just increments reference counter. */
78  DeviceArray(const DeviceArray& other);
79 
80  /** \brief Assignment operator. Just increments reference counter. */
82  operator=(const DeviceArray& other);
83 
84  /** \brief Allocates internal buffer in GPU memory. If internal buffer was created
85  * before the function recreates it with new size. If new and old sizes are equal it
86  * does nothing.
87  * \param size elements number
88  * */
89  void
90  create(std::size_t size);
91 
92  /** \brief Decrements reference counter and releases internal buffer if needed. */
93  void
94  release();
95 
96  /** \brief Performs data copying. If destination size differs it will be reallocated.
97  * \param other destination container
98  * */
99  void
100  copyTo(DeviceArray& other) const;
101 
102  /** \brief Uploads data to internal buffer in GPU memory. It calls create() inside to
103  * ensure that internal buffer size is enough.
104  * \param host_ptr pointer to buffer to upload
105  * \param size elements number
106  * */
107  void
108  upload(const T* host_ptr, std::size_t size);
109 
110  /** \brief Uploads data from CPU memory to internal buffer.
111  * \return true if upload successful
112  * \note In contrast to the other upload function, this function
113  * never allocates memory.
114  * \param host_ptr pointer to buffer to upload
115  * \param device_begin_offset begin upload
116  * \param num_elements number of elements from device_bein_offset
117  * */
118  bool
119  upload(const T* host_ptr, std::size_t device_begin_offset, std::size_t num_elements);
120 
121  /** \brief Downloads data from internal buffer to CPU memory
122  * \param host_ptr pointer to buffer to download
123  * */
124  void
125  download(T* host_ptr) const;
126 
127  /** \brief Downloads data from internal buffer to CPU memory.
128  * \return true if download successful
129  * \param host_ptr pointer to buffer to download
130  * \param device_begin_offset begin download location
131  * \param num_elements number of elements from device_begin_offset
132  * */
133  bool
134  download(T* host_ptr,
135  std::size_t device_begin_offset,
136  std::size_t num_elements) const;
137 
138  /** \brief Uploads data to internal buffer in GPU memory. It calls create() inside to
139  * ensure that internal buffer size is enough.
140  * \param data host vector to upload from
141  * */
142  template <class A>
143  void
144  upload(const std::vector<T, A>& data);
145 
146  /** \brief Downloads data from internal buffer to CPU memory
147  * \param data host vector to download to
148  * */
149  template <typename A>
150  void
151  download(std::vector<T, A>& data) const;
152 
153  /** \brief Performs swap of data pointed with another device array.
154  * \param other_arg device array to swap with
155  * */
156  void
157  swap(DeviceArray& other_arg);
158 
159  /** \brief Returns pointer for internal buffer in GPU memory. */
160  T*
161  ptr();
162 
163  /** \brief Returns const pointer for internal buffer in GPU memory. */
164  const T*
165  ptr() const;
166 
167  // using DeviceMemory::ptr;
168 
169  /** \brief Returns pointer for internal buffer in GPU memory. */
170  operator T*();
171 
172  /** \brief Returns const pointer for internal buffer in GPU memory. */
173  operator const T*() const;
174 
175  /** \brief Returns size in elements. */
176  std::size_t
177  size() const;
178 };
179 
180 ///////////////////////////////////////////////////////////////////////////////
181 /** \brief @b DeviceArray2D class
182  *
183  * \note Typed container for pitched GPU memory with reference counting.
184  *
185  * \author Anatoly Baksheev
186  */
187 template <class T>
189 public:
190  /** \brief Element type. */
191  using type = T;
192 
193  /** \brief Element size. */
194  enum { elem_size = sizeof(T) };
195 
196  /** \brief Empty constructor. */
197  DeviceArray2D();
198 
199  /** \brief Allocates internal buffer in GPU memory
200  * \param rows number of rows to allocate
201  * \param cols number of elements in each row
202  * */
203  DeviceArray2D(int rows, int cols);
204 
205  /** \brief Initializes with user allocated buffer. Reference counting is disabled in
206  * this case.
207  * \param rows number of rows
208  * \param cols number of elements in each row
209  * \param data pointer to buffer
210  * \param stepBytes stride between two consecutive rows in bytes
211  * */
212  DeviceArray2D(int rows, int cols, void* data, std::size_t stepBytes);
213 
214  /** \brief Copy constructor. Just increments reference counter. */
215  DeviceArray2D(const DeviceArray2D& other);
216 
217  /** \brief Assignment operator. Just increments reference counter. */
219  operator=(const DeviceArray2D& other);
220 
221  /** \brief Allocates internal buffer in GPU memory. If internal buffer was created
222  * before the function recreates it with new size. If new and old sizes are equal it
223  * does nothing.
224  * \param rows number of rows to allocate
225  * \param cols number of elements in each row
226  * */
227  void
228  create(int rows, int cols);
229 
230  /** \brief Decrements reference counter and releases internal buffer if needed. */
231  void
232  release();
233 
234  /** \brief Performs data copying. If destination size differs it will be reallocated.
235  * \param other destination container
236  * */
237  void
238  copyTo(DeviceArray2D& other) const;
239 
240  /** \brief Uploads data to internal buffer in GPU memory. It calls create() inside to
241  * ensure that internal buffer size is enough.
242  * \param host_ptr pointer to host buffer to upload
243  * \param host_step stride between two consecutive rows in bytes for host buffer
244  * \param rows number of rows to upload
245  * \param cols number of elements in each row
246  * */
247  void
248  upload(const void* host_ptr, std::size_t host_step, int rows, int cols);
249 
250  /** \brief Downloads data from internal buffer to CPU memory. User is responsible for
251  * correct host buffer size.
252  * \param host_ptr pointer to host buffer to download
253  * \param host_step stride between two consecutive rows in bytes for host buffer
254  * */
255  void
256  download(void* host_ptr, std::size_t host_step) const;
257 
258  /** \brief Performs swap of data pointed with another device array.
259  * \param other_arg device array to swap with
260  * */
261  void
262  swap(DeviceArray2D& other_arg);
263 
264  /** \brief Uploads data to internal buffer in GPU memory. It calls create() inside to
265  * ensure that internal buffer size is enough.
266  * \param data host vector to upload from
267  * \param cols stride in elements between two consecutive rows for host buffer
268  * */
269  template <class A>
270  void
271  upload(const std::vector<T, A>& data, int cols);
272 
273  /** \brief Downloads data from internal buffer to CPU memory
274  * \param data host vector to download to
275  * \param cols Output stride in elements between two consecutive rows for host vector.
276  * */
277  template <class A>
278  void
279  download(std::vector<T, A>& data, int& cols) const;
280 
281  /** \brief Returns pointer to given row in internal buffer.
282  * \param y row index
283  * */
284  T*
285  ptr(int y = 0);
286 
287  /** \brief Returns const pointer to given row in internal buffer.
288  * \param y row index
289  * */
290  const T*
291  ptr(int y = 0) const;
292 
293  // using DeviceMemory2D::ptr;
294 
295  /** \brief Returns pointer for internal buffer in GPU memory. */
296  operator T*();
297 
298  /** \brief Returns const pointer for internal buffer in GPU memory. */
299  operator const T*() const;
300 
301  /** \brief Returns number of elements in each row. */
302  int
303  cols() const;
304 
305  /** \brief Returns number of rows. */
306  int
307  rows() const;
308 
309  /** \brief Returns step in elements. */
310  std::size_t
311  elem_step() const;
312 };
313 } // namespace gpu
314 
315 namespace device {
318 } // namespace device
319 } // namespace pcl
320 
321 #include <pcl/gpu/containers/impl/device_array.hpp>
DeviceArray2D class
Definition: device_array.h:188
DeviceArray class
Definition: device_array.h:54
T type
Element type.
Definition: device_array.h:57
DeviceMemory2D class
DeviceMemory class
Definition: device_memory.h:54
#define PCL_EXPORTS
Definition: pcl_macros.h:323