- Main Page
- Modules
- Namespaces
- Classes
- Files

- Search for |

- File List
- File Members

# include/NvBuffer.h

Go to the documentation of this file.

    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