00001 /* 00002 * Copyright (c) 2016, NVIDIA CORPORATION. All rights reserved. 00003 * 00004 * Redistribution and use in source and binary forms, with or without 00005 * modification, are permitted provided that the following conditions 00006 * are met: 00007 * * Redistributions of source code must retain the above copyright 00008 * notice, this list of conditions and the following disclaimer. 00009 * * Redistributions in binary form must reproduce the above copyright 00010 * notice, this list of conditions and the following disclaimer in the 00011 * documentation and/or other materials provided with the distribution. 00012 * * Neither the name of NVIDIA CORPORATION nor the names of its 00013 * contributors may be used to endorse or promote products derived 00014 * from this software without specific prior written permission. 00015 * 00016 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND ANY 00017 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 00018 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 00019 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 00020 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 00021 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 00022 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 00023 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY 00024 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 00025 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 00026 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00027 */ 00028 00029 /** 00030 * @file 00031 * <b>NVIDIA Eagle Eye API: Buffer API</b> 00032 * 00033 * @b Description: This file declares the NvBuffer APIs. 00034 */ 00035 00036 #ifndef __NV_BUFFER_H__ 00037 #define __NV_BUFFER_H__ 00038 00039 #include <linux/videodev2.h> 00040 #include <pthread.h> 00041 #include <stdint.h> 00042 00043 #include "v4l2_nv_extensions.h" 00044 00045 /** 00046 * 00047 * @defgroup ee_nvbuffer_group Buffer API 00048 * 00049 * The @c %NvBuffer API provides buffer functionality, including reference 00050 * count functionality and convenience methods. 00051 * 00052 * @{ 00053 */ 00054 00055 /** 00056 * Specifies the maximum number of planes a buffer can contain. 00057 */ 00058 #define MAX_PLANES 3 00059 00060 /** 00061 * @brief Class representing a buffer. 00062 * 00063 * The NvBuffer class is modeled on the basis of the @c v4l2_buffer 00064 * structure. The buffer has @c buf_type @c v4l2_buf_type, @c 00065 * memory_type @c v4l2_memory, and an index. It contains an 00066 * NvBufferPlane array similar to the array of @c v4l2_plane 00067 * structures in @c v4l2_buffer.m.planes. It also contains a 00068 * corresponding NvBufferPlaneFormat array that describes the 00069 * format of each of the planes. 00070 * 00071 * Even though @c %NvBuffer closely resembles v4l2 structures, it can 00072 * be easily used with other non-v4l2 components. @c %NvBuffer 00073 * contains data pointers, buffer length, file descriptor (FD) of 00074 * buffer planes, buffer format (height, width, stride, etc.), and 00075 * other members that are required by such components. 00076 * 00077 * This class also provides buffer reference count functionality. This 00078 * is useful when the same buffer is being used by multiple elements. 00079 * 00080 * In the case of a V4L2 MMAP, this class provides convenience methods 00081 * for mapping or unmapping the contents of the buffer to or from 00082 * memory, allocating or deallocating software memory depending on its 00083 * format. 00084 */ 00085 class NvBuffer 00086 { 00087 public: 00088 /** 00089 * Holds the buffer plane format. 00090 */ 00091 typedef struct 00092 { 00093 uint32_t width; /**< Holds the width of the plane in pixels. */ 00094 uint32_t height; /**< Holds the height of the plane in pixels. */ 00095 00096 uint32_t bytesperpixel; /**< Holds the bytes used to represent one 00097 pixel in the plane. */ 00098 uint32_t stride; /**< Holds the stride of the plane in bytes. */ 00099 uint32_t sizeimage; /**< Holds the size of the plane in bytes. */ 00100 } NvBufferPlaneFormat; 00101 00102 /** 00103 * Holds the buffer plane parameters. 00104 */ 00105 typedef struct 00106 { 00107 NvBufferPlaneFormat fmt; /**< Holds the format of the plane. */ 00108 00109 unsigned char *data; /**< Holds a pointer to the plane memory. */ 00110 uint32_t bytesused; /**< Holds the number of valid bytes in the plane. */ 00111 00112 int fd; /**< Holds the file descriptor (FD) of the plane of the 00113 exported buffer, in the case of V4L2 MMAP buffers. */ 00114 uint32_t mem_offset; /**< Holds the offset of the first valid byte 00115 from the data pointer. */ 00116 uint32_t length; /**< Holds the size of the buffer in bytes. */ 00117 } NvBufferPlane; 00118 00119 /** 00120 * Creates a new NvBuffer object. 00121 * 00122 * This convenience method for V4L2 elements creates a new buffer 00123 * with the planes array memset to zero and the refcount 00124 * initialized to zero. 00125 * 00126 00127 * @param[in] buf_type Specifies the type of buffer, enumerated as @c 00128 * v4l2_buf_type. 00129 * @param[in] memory_type Specifies the @c %NvBuffer memory, enumerated as a 00130 * @c v4l2_memory enum. 00131 * @param[in] n_planes Specifies the number of planes in the buffer. 00132 * @param[in] fmt Specifies a pointer to the array of buffer plane formats. 00133 * Should contain at least @a n_planes elements. 00134 * @param[in] index Specifies the index of the buffer in the plane. 00135 */ 00136 NvBuffer(enum v4l2_buf_type buf_type, enum v4l2_memory memory_type, 00137 uint32_t n_planes, NvBufferPlaneFormat *fmt, uint32_t index); 00138 00139 /** 00140 * Creates a new NvBuffer for raw pixel formats. 00141 * 00142 * This convenience method for V4L2 elements is an @c %NvBuffer 00143 * constructor for raw pixel formats only. It requires width, 00144 * height, and pixel format to be specified. 00145 * 00146 * The planes array is memset to zero and the refcount is 00147 * initialized to zero. 00148 * 00149 * @attention The memory must be allocated by the application 00150 * by calling NvBuffer::allocateMemory. 00151 * 00152 * @param[in] pixfmt Specifies the pixel format of the buffer. 00153 * @param[in] width Specifies the width of the buffer in pixels. 00154 * @param[in] height Specifies the height of the buffer in pixels. 00155 * @param[in] index Specifies the index/ID of the buffer. 00156 */ 00157 NvBuffer(uint32_t pixfmt, uint32_t width, uint32_t height, uint32_t index); 00158 00159 /** 00160 * Creates a new NvBuffer object for non-raw pixel formats. 00161 * 00162 * This convenience method for V4L2 elements is an @c %NvBuffer 00163 * constructor for non raw pixel formats. It requires size of the 00164 * buffer to be supplied. 00165 * 00166 * The planes array is memset to zero and refcount initialized to 00167 * zero. 00168 * 00169 * @attention The memory needs to be allocated by the application 00170 * by calling NvBuffer::allocateMemory. 00171 * 00172 * @param[in] size Specifies the size of the buffer in bytes. 00173 * @param[in] index Specifies the index/ID of the buffer. 00174 */ 00175 NvBuffer(uint32_t size, uint32_t index); 00176 00177 /** 00178 * Destroys an NvBuffer object. 00179 * 00180 * This method cleans up class instances, unmapping any mapped 00181 * planes. 00182 */ 00183 ~NvBuffer(); 00184 00185 /** 00186 * Maps the contents of the buffer to memory. 00187 * 00188 * This method maps the file descriptor (FD) of the planes to 00189 * a data pointer of @c planes. (MMAP buffers only.) 00190 * 00191 * @return 0 on success, -1 otherwise. 00192 */ 00193 int map(); 00194 /** 00195 * Unmaps the contents of the buffer from memory. (MMAP buffers only.) 00196 * 00197 */ 00198 void unmap(); 00199 00200 /** 00201 * Allocates software memory for the buffer. 00202 * 00203 * @warning This method works only for @c V4L2_MEMORY_USERPTR memory. 00204 * 00205 * This method allocates memory on the basis of the buffer format: 00206 * @a height, @a width, @a bytesperpixel, and @a sizeimage. 00207 * 00208 * @return 0 for success, -1 otherwise. 00209 */ 00210 int allocateMemory(); 00211 /** 00212 * Deallocates buffer memory. 00213 * 00214 * @warning This method works only for @c V4L2_MEMORY_USERPTR memory and if 00215 * the memory was previously allocated using NvBuffer::allocateMemory. 00216 */ 00217 void deallocateMemory(); 00218 00219 /** 00220 * Increases the reference count of the buffer. 00221 * 00222 * This method is thread safe. 00223 * 00224 * @return Reference count of the buffer after the operation. 00225 */ 00226 int ref(); 00227 /** 00228 * Decreases the reference count of the buffer. 00229 * 00230 * This thread-safe method decreases the buffer reference count if the 00231 * buffer reference count is above 0. 00232 * 00233 * @return Reference count of the buffer after the operation. 00234 */ 00235 int unref(); 00236 00237 const enum v4l2_buf_type buf_type; /**< SpecifiesOB the type of the buffer. */ 00238 const enum v4l2_memory memory_type; /**< Specifies the type of memory associated 00239 with the buffer. */ 00240 00241 const uint32_t index; /**< Holds the buffer index. */ 00242 00243 uint32_t n_planes; /**< Holds the number of planes in the buffer. */ 00244 NvBufferPlane planes[MAX_PLANES]; /**< Holds the data pointer, plane file 00245 descriptor (FD), plane format, etc. */ 00246 00247 /** 00248 * Fills the NvBuffer::NvBufferPlaneFormat array. 00249 * 00250 * This convenience method populates the 00251 * @c %NvBuffer::NvBufferPlaneFormat array on the basis of @a width, 00252 * @a height and pixel format (@a raw_pixfmt). It also returns the number of planes 00253 * required for the pixel format in @a num_planes. 00254 * 00255 * 00256 * @param[out] num_planes Indicates the number of planes. Must not be NULL. 00257 * @param[in,out] planefmts Array of NvBuffer::NvBufferPlaneFormat to 00258 * fill. Should be atleast \a num_planes in length. For best 00259 * results, pass an array of length #MAX_PLANES. 00260 * @param[in] width Specifies the width of the buffer in pixels. 00261 * @param[in] height Specifies the height of the buffer in pixels. 00262 * @param[in] raw_pixfmt Specifies one of the raw V4L2 pixel formats. 00263 * @return 0 for success, -1 for an unsupported pixel format. 00264 */ 00265 static int fill_buffer_plane_format(uint32_t *num_planes, 00266 NvBuffer::NvBufferPlaneFormat *planefmts, 00267 uint32_t width, uint32_t height, uint32_t raw_pixfmt); 00268 private: 00269 uint32_t ref_count; /**< Holds the reference count of the buffer. */ 00270 pthread_mutex_t ref_lock; /**< Mutex to synchronize increment/ 00271 decrement operations of @c ref_count. */ 00272 00273 bool mapped; /**< Indicates if the buffer is mapped to 00274 memory. */ 00275 bool allocated; /**< Indicates if the buffer is allocated 00276 memory. */ 00277 NvBuffer *shared_buffer; /**< If this is a DMABUF buffer, @c shared_buffer 00278 points to the MMAP @c NvBuffer whose FD was 00279 sent when this buffer was queued. */ 00280 00281 /** 00282 * Disallow copy constructor. 00283 */ 00284 NvBuffer(const NvBuffer& that); 00285 /** 00286 * Disallow assignment. 00287 */ 00288 void operator=(NvBuffer const&); 00289 00290 friend class NvV4l2ElementPlane; 00291 }; 00292 /** @} */ 00293 #endif