xbmc/utils/IBufferObject.h

   1 /*
   2  *  Copyright (C) 2017-2018 Team Kodi
   3  *  This file is part of Kodi - https://kodi.tv
   4  *
   5  *  SPDX-License-Identifier: GPL-2.0-or-later
   6  *  See LICENSES/README.md for more information.
   7  */
   8
   9 #pragma once
  10
  11 #include <stdint.h>
  12 #include <string>
  13
  14 /**
  15  * @brief Interface to describe CBufferObjects.
  16  *
  17  *        BufferObjects are used to abstract various memory types and present them
  18  *        with a generic interface. Typically on a posix system exists the concept
  19  *        of Direct Memory Access (DMA) which allows various systems to interact
  20  *        with a memory location directly without having to copy the data into
  21  *        userspace (ie. from kernel space). These DMA buffers are presented as
  22  *        file descriptors (fds) which can be passed around to gain access to
  23  *        the buffers memory location.
  24  *
  25  *        In order to write to these buffer types typically the memory location has
  26  *        to be mapped into userspace via a call to mmap (or similar). This presents
  27  *        userspace with a memory location that can be initially written to (ie. by
  28  *        using memcpy or similar). Depending on the underlying implementation a
  29  *        stride might be specified if the memory type requires padding to a certain
  30  *        size (such as page size). The stride must be used when copying into the buffer.
  31  *
  32  *        Some memory implementation may provide special memory layouts in which case
  33  *        modifiers are provided that describe tiling or compression. This should be
  34  *        transparent to the caller as the data copied into a BufferObject will likely
  35  *        be linear. The modifier will be needed when presenting the buffer via DRM or
  36  *        EGL even if it is linear.
  37  *
  38  */
  39 class IBufferObject
  40 {
  41 public:
  42   virtual ~IBufferObject() = default;
  43
  44   /**
  45    * @brief Create a BufferObject based on the format, width, and height of the desired buffer
  46    *
  47    * @param format framebuffer pixel formats are described using the fourcc codes defined in
  48    *               https://github.com/torvalds/linux/blob/master/include/uapi/drm/drm_fourcc.h
  49    * @param width width of the requested buffer.
  50    * @param height height of the requested buffer.
  51    * @return true BufferObject creation was successful.
  52    * @return false BufferObject creation was unsuccessful.
  53    */
  54   virtual bool CreateBufferObject(uint32_t format, uint32_t width, uint32_t height) = 0;
  55
  56   /**
  57    * @brief Create a BufferObject based only on the size of the desired buffer. Not all
  58    *        CBufferObject implementations may support this. This method is required for
  59    *        use with the CAddonVideoCodec as it only knows the decoded buffer size.
  60    *
  61    * @param size of the requested buffer.
  62    * @return true BufferObject creation was successful.
  63    * @return false BufferObject creation was unsuccessful.
  64    */
  65   virtual bool CreateBufferObject(uint64_t size) = 0;
  66
  67   /**
  68    * @brief Destroy a BufferObject.
  69    *
  70    */
  71   virtual void DestroyBufferObject() = 0;
  72
  73   /**
  74    * @brief Get the Memory location of the BufferObject. This method needs to be
  75    *        called to be able to copy data into the BufferObject.
  76    *
  77    * @return uint8_t* pointer to the memory location of the BufferObject.
  78    */
  79   virtual uint8_t *GetMemory() = 0;
  80
  81   /**
  82    * @brief Release the mapped memory of the BufferObject. After calling this the memory
  83    *        location pointed to by GetMemory() will be invalid.
  84    *
  85    */
  86   virtual void ReleaseMemory() = 0;
  87
  88   /**
  89    * @brief Get the File Descriptor of the BufferObject. The fd is guaranteed to be
  90    *        available after calling CreateBufferObject().
  91    *
  92    * @return int fd for the BufferObject. Invalid if -1.
  93    */
  94   virtual int GetFd() = 0;
  95
  96   /**
  97    * @brief Get the Stride of the BufferObject. The stride is guaranteed to be
  98    *        available after calling GetMemory().
  99    *
 100    * @return uint32_t stride of the BufferObject.
 101    */
 102   virtual uint32_t GetStride() = 0;
 103
 104   /**
 105    * @brief Get the Modifier of the BufferObject. Format Modifiers further describe
 106    *        the buffer's format such as for tiling or compression.
 107    *        see https://github.com/torvalds/linux/blob/master/include/uapi/drm/drm_fourcc.h
 108    *
 109    * @return uint64_t modifier of the BufferObject. 0 means the layout is linear (default).
 110    */
 111   virtual uint64_t GetModifier() = 0;
 112
 113   /**
 114    * @brief Must be called before reading/writing data to the BufferObject.
 115    *
 116    */
 117   virtual void SyncStart() = 0;
 118
 119   /**
 120    * @brief Must be called after reading/writing data to the BufferObject.
 121    *
 122    */
 123   virtual void SyncEnd() = 0;
 124
 125   /**
 126    * @brief Get the Name of the BufferObject type in use
 127    *
 128    * @return std::string name of the BufferObject type in use
 129    */
 130   virtual std::string GetName() const = 0;
 131 };