# NvBuffer Class Reference
[Buffer API]

Class representing a buffer. More...

`#include <NvBuffer.h>`

List of all members.

## Classes

struct | NvBufferPlane
| Holds the buffer plane parameters. More...
struct | NvBufferPlaneFormat
| Holds the buffer plane format. More...

## Public Member Functions

| NvBuffer (enum v4l2_buf_type buf_type, enum v4l2_memory memory_type, uint32_t n_planes, NvBufferPlaneFormat *fmt, uint32_t index)
| Creates a new NvBuffer object.
| NvBuffer (uint32_t pixfmt, uint32_t width, uint32_t height, uint32_t index)
| Creates a new NvBuffer for raw pixel formats.
| NvBuffer (uint32_t size, uint32_t index)
| Creates a new NvBuffer object for non-raw pixel formats.
| ~NvBuffer ()
| Destroys an NvBuffer object.
int | map ()
| Maps the contents of the buffer to memory.
void | unmap ()
| Unmaps the contents of the buffer from memory.
int | allocateMemory ()
| Allocates software memory for the buffer.
void | deallocateMemory ()
| Deallocates buffer memory.
int | ref ()
| Increases the reference count of the buffer.
int | unref ()
| Decreases the reference count of the buffer.

## Static Public Member Functions

static int | fill_buffer_plane_format (uint32_t *num_planes, NvBuffer::NvBufferPlaneFormat *planefmts, uint32_t width, uint32_t height, uint32_t raw_pixfmt)
| Fills the NvBuffer::NvBufferPlaneFormat array.

## Public Attributes

enum v4l2_buf_type | buf_type
| SpecifiesOB the type of the buffer.
enum v4l2_memory | memory_type
| Specifies the type of memory associated with the buffer.
const uint32_t | index
| Holds the buffer index.
uint32_t | n_planes
| Holds the number of planes in the buffer.
NvBufferPlane | planes [MAX_PLANES]
| Holds the data pointer, plane file descriptor (FD), plane format, etc.

## Private Member Functions

| NvBuffer (const NvBuffer &that)
| Disallow copy constructor.
void | operator= (NvBuffer const &)
| Disallow assignment.

## Private Attributes

uint32_t | ref_count
| Holds the reference count of the buffer.
pthread_mutex_t | ref_lock
| Mutex to synchronize increment/ decrement operations of `ref_count`.
bool | mapped
| Indicates if the buffer is mapped to memory.
bool | allocated
| Indicates if the buffer is allocated memory.
NvBuffer * | shared_buffer
| If this is a DMABUF buffer, `shared_buffer` points to the MMAP `NvBuffer` whose FD was sent when this buffer was queued.

## Friends

class | NvV4l2ElementPlane

## Detailed Description

Class representing a buffer.

The NvBuffer class is modeled on the basis of the `v4l2_buffer` structure. The buffer has `buf_type` `v4l2_buf_type`, `memory_type` `v4l2_memory`, and an index. It contains an NvBufferPlane array similar to the array of `v4l2_plane` structures in `v4l2_buffer.m.planes`. It also contains a corresponding NvBufferPlaneFormat array that describes the format of each of the planes.

Even though `NvBuffer` closely resembles v4l2 structures, it can be easily used with other non-v4l2 components. `NvBuffer` contains data pointers, buffer length, file descriptor (FD) of buffer planes, buffer format (height, width, stride, etc.), and other members that are required by such components.

This class also provides buffer reference count functionality. This is useful when the same buffer is being used by multiple elements.

In the case of a V4L2 MMAP, this class provides convenience methods for mapping or unmapping the contents of the buffer to or from memory, allocating or deallocating software memory depending on its format.

Definition at line 85 of file NvBuffer.h.

## Constructor & Destructor Documentation

NvBuffer::NvBuffer | ( | enum v4l2_buf_type | buf_type,
|  | enum v4l2_memory | memory_type,
|  | uint32_t | n_planes,
|  | NvBufferPlaneFormat * | fmt,
|  | uint32_t | index |
| ) |  |  |

Creates a new NvBuffer object.

This convenience method for V4L2 elements creates a new buffer with the planes array memset to zero and the refcount initialized to zero.

Parameters:

  `[in]` | buf_type | Specifies the type of buffer, enumerated as `v4l2_buf_type`.
  `[in]` | memory_type | Specifies the `NvBuffer` memory, enumerated as a `v4l2_memory` enum.
  `[in]` | n_planes | Specifies the number of planes in the buffer.
  `[in]` | fmt | Specifies a pointer to the array of buffer plane formats. Should contain at least n_planes elements.
  `[in]` | index | Specifies the index of the buffer in the plane.

Definition at line 41 of file NvBuffer.cpp.

NvBuffer::NvBuffer | ( | uint32_t | pixfmt,
|  | uint32_t | width,
|  | uint32_t | height,
|  | uint32_t | index |
| ) |  |  |

Creates a new NvBuffer for raw pixel formats.

This convenience method for V4L2 elements is an `NvBuffer` constructor for raw pixel formats only. It requires width, height, and pixel format to be specified.

The planes array is memset to zero and the refcount is initialized to zero.

Attention:
  The memory must be allocated by the application by calling NvBuffer::allocateMemory.

Parameters:

  `[in]` | pixfmt | Specifies the pixel format of the buffer.
  `[in]` | width | Specifies the width of the buffer in pixels.
  `[in]` | height | Specifies the height of the buffer in pixels.
  `[in]` | index | Specifies the index/ID of the buffer.

Definition at line 65 of file NvBuffer.cpp.

NvBuffer::NvBuffer | ( | uint32_t | size,
|  | uint32_t | index |
| ) |  |  |

Creates a new NvBuffer object for non-raw pixel formats.

This convenience method for V4L2 elements is an `NvBuffer` constructor for non raw pixel formats. It requires size of the buffer to be supplied.

The planes array is memset to zero and refcount initialized to zero.

Attention:
  The memory needs to be allocated by the application by calling NvBuffer::allocateMemory.

Parameters:

  `[in]` | size | Specifies the size of the buffer in bytes.
  `[in]` | index | Specifies the index/ID of the buffer.

Definition at line 97 of file NvBuffer.cpp.

NvBuffer::~NvBuffer | ( |  | ) |

Destroys an NvBuffer object.

This method cleans up class instances, unmapping any mapped planes.

Definition at line 123 of file NvBuffer.cpp.

NvBuffer::NvBuffer | ( | const NvBuffer & | that | ) | `[private]`

Disallow copy constructor.

## Member Function Documentation

int NvBuffer::allocateMemory | ( |  | ) |

Allocates software memory for the buffer.

Warning:
  This method works only for `V4L2_MEMORY_USERPTR` memory.

This method allocates memory on the basis of the buffer format: height, width, bytesperpixel, and sizeimage.

Returns:
  0 for success, -1 otherwise.

Definition at line 205 of file NvBuffer.cpp.

void NvBuffer::deallocateMemory | ( |  | ) |

Deallocates buffer memory.

Warning:
  This method works only for `V4L2_MEMORY_USERPTR` memory and if the memory was previously allocated using NvBuffer::allocateMemory.

Definition at line 253 of file NvBuffer.cpp.

int NvBuffer::fill_buffer_plane_format | ( | uint32_t * | num_planes,
|  | NvBuffer::NvBufferPlaneFormat * | planefmts,
|  | uint32_t | width,
|  | uint32_t | height,
|  | uint32_t | raw_pixfmt |
| ) |  |  | `[static]`

Fills the NvBuffer::NvBufferPlaneFormat array.

This convenience method populates the `NvBufferNvBufferPlaneFormat` array on the basis of width, height and pixel format (raw_pixfmt). It also returns the number of planes required for the pixel format in num_planes.

Parameters:

  `[out]` | num_planes | Indicates the number of planes. Must not be NULL.
  `[in,out]` | planefmts | Array of NvBuffer::NvBufferPlaneFormat to fill. Should be atleast num_planes in length. For best results, pass an array of length MAX_PLANES.
  `[in]` | width | Specifies the width of the buffer in pixels.
  `[in]` | height | Specifies the height of the buffer in pixels.
  `[in]` | raw_pixfmt | Specifies one of the raw V4L2 pixel formats.

Returns:
  0 for success, -1 for an unsupported pixel format.

Definition at line 305 of file NvBuffer.cpp.

int NvBuffer::map | ( |  | ) |

Maps the contents of the buffer to memory.

This method maps the file descriptor (FD) of the planes to a data pointer of `planes`. (MMAP buffers only.)

Returns:
  0 on success, -1 otherwise.

Definition at line 138 of file NvBuffer.cpp.

void NvBuffer::operator= | ( | NvBuffer const & |  | ) | `[private]`

Disallow assignment.

int NvBuffer::ref | ( |  | ) |

Increases the reference count of the buffer.

This method is thread safe.

Returns:
  Reference count of the buffer after the operation.

Definition at line 279 of file NvBuffer.cpp.

void NvBuffer::unmap | ( |  | ) |

Unmaps the contents of the buffer from memory.

(MMAP buffers only.)

Definition at line 183 of file NvBuffer.cpp.

int NvBuffer::unref | ( |  | ) |

Decreases the reference count of the buffer.

This thread-safe method decreases the buffer reference count if the buffer reference count is above 0.

Returns:
  Reference count of the buffer after the operation.

Definition at line 290 of file NvBuffer.cpp.

## Friends And Related Function Documentation

friend class NvV4l2ElementPlane `[friend]`

Definition at line 290 of file NvBuffer.h.

## Member Data Documentation

bool NvBuffer::allocated `[private]`

Indicates if the buffer is allocated memory.

Definition at line 275 of file NvBuffer.h.

enum v4l2_buf_type NvBuffer::buf_type

SpecifiesOB the type of the buffer.

Definition at line 237 of file NvBuffer.h.

const uint32_t NvBuffer::index

Holds the buffer index.

Definition at line 241 of file NvBuffer.h.

bool NvBuffer::mapped `[private]`

Indicates if the buffer is mapped to memory.

Definition at line 273 of file NvBuffer.h.

enum v4l2_memory NvBuffer::memory_type

Specifies the type of memory associated with the buffer.

Definition at line 238 of file NvBuffer.h.

uint32_t NvBuffer::n_planes

Holds the number of planes in the buffer.

Definition at line 243 of file NvBuffer.h.

NvBufferPlane NvBuffer::planes[MAX_PLANES]

Holds the data pointer, plane file descriptor (FD), plane format, etc.

Definition at line 244 of file NvBuffer.h.

uint32_t NvBuffer::ref_count `[private]`

Holds the reference count of the buffer.

Definition at line 269 of file NvBuffer.h.

pthread_mutex_t NvBuffer::ref_lock `[private]`

Mutex to synchronize increment/ decrement operations of `ref_count`.

Definition at line 270 of file NvBuffer.h.

NvBuffer* NvBuffer::shared_buffer `[private]`

If this is a DMABUF buffer, `shared_buffer` points to the MMAP `NvBuffer` whose FD was sent when this buffer was queued.

Definition at line 277 of file NvBuffer.h.

The documentation for this class was generated from the following files:

- include/NvBuffer.h
- samples/common/classes/NvBuffer.cpp