dali/graphics-api/graphics-memory.h

   1 #ifndef DALI_GRAPHICS_MEMORY_H
   2 #define DALI_GRAPHICS_MEMORY_H
   3
   4 /*
   5  * Copyright (c) 2021 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // EXTERNAL INCLUDES
  22 #include <cstdint>
  23
  24 namespace Dali
  25 {
  26 namespace Graphics
  27 {
  28 /**
  29  * @brief Memory object represents a GPU memory that can be
  30  * read and/or written.
  31  *
  32  * It depends on the usage when creating objects such as
  33  * buffers and textures.
  34  *
  35  * The Memory must be mapped first, however, to obtain the direct
  36  * pointer the memory must be locked. Locking mechanism enables
  37  * synchronisation and prevents driver from using the memory
  38  * until the client unlocks it. The memory may be still used
  39  * while being mapped (it's ok to keep memory mapped persistently).
  40  *
  41  */
  42 class Memory
  43 {
  44 public:
  45   Memory()          = default;
  46   virtual ~Memory() = default;
  47
  48   // not copyable
  49   Memory(const Memory&) = delete;
  50   Memory& operator=(const Memory&) = delete;
  51
  52   /**
  53    * @brief Locks region of memory for client-side operation
  54    *
  55    * @param[in] offset Offset of mapped memory
  56    * @param[in] size Size of the region to be locked
  57    * @return returns valid memory pointer or nullptr on failure
  58    */
  59   virtual void* LockRegion(uint32_t offset, uint32_t size) = 0;
  60
  61   /**
  62    * @brief Unlocks previously locked memory region
  63    *
  64    * @param[in] flush If true, region will be flushed immediately and visible to GPU
  65    */
  66   virtual void Unlock(bool flush) = 0;
  67
  68   /**
  69   * @brief Flushes memory
  70   *
  71   * Flushing makes a memory object instantly visible by the GPU.
  72   *
  73   * Example:
  74   * Large Buffer object divided in two halves. Every frame only one half
  75   * is being updated (permanently mapped, locked, written, unlocked). Calling
  76   * FlushMemory() we can update the GPU without unmapping the Buffer object.
  77   *
  78   * In the scenario when the Memory is being unmapped, flushing is redundant.
  79   */
  80   virtual void Flush() = 0;
  81
  82 protected:
  83   Memory(Memory&&) = default;
  84   Memory& operator=(Memory&&) = default;
  85 };
  86
  87 } // Namespace Graphics
  88 } // Namespace Dali
  89
  90 #endif