| /* |
| * Copyright (C) 2016 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| #ifndef C2BUFFER_H_ |
| #define C2BUFFER_H_ |
| |
| #include <C2.h> |
| #include <C2BufferBase.h> |
| #include <C2Param.h> // for C2Info |
| |
| #include <memory> |
| #include <vector> |
| |
| #ifdef __ANDROID__ |
| #include <android-C2Buffer.h> |
| #else |
| |
| typedef void* C2Handle; |
| |
| #endif |
| |
| /// \defgroup buffer Buffers |
| /// @{ |
| |
| /// \defgroup buffer_sync Synchronization |
| /// @{ |
| |
| /** |
| * Synchronization is accomplished using event and fence objects. |
| * |
| * These are cross-process extensions of promise/future infrastructure. |
| * Events are analogous to std::promise<void>, whereas fences are to std::shared_future<void>. |
| * |
| * Fences and events are shareable/copyable. |
| * |
| * Fences are used in two scenarios, and all copied instances refer to the same event. |
| * \todo do events need to be copyable or should they be unique? |
| * |
| * acquire sync fence object: signaled when it is safe for the component or client to access |
| * (the contents of) an object. |
| * |
| * release sync fence object: \todo |
| * |
| * Fences can be backed by hardware. Hardware fences are guaranteed to signal NO MATTER WHAT within |
| * a short (platform specific) amount of time; this guarantee is usually less than 15 msecs. |
| */ |
| |
| /** |
| * Fence object used by components and the framework. |
| * |
| * Implements the waiting for an event, analogous to a 'future'. |
| * |
| * To be implemented by vendors if using HW fences. |
| */ |
| class C2Fence { |
| public: |
| /** |
| * Waits for a fence to be signaled with a timeout. |
| * |
| * \todo a mechanism to cancel a wait - for now the only way to do this is to abandon the |
| * event, but fences are shared so canceling a wait will cancel all waits. |
| * |
| * \param timeoutNs the maximum time to wait in nsecs |
| * |
| * \retval C2_OK the fence has been signaled |
| * \retval C2_TIMED_OUT the fence has not been signaled within the timeout |
| * \retval C2_BAD_STATE the fence has been abandoned without being signaled (it will never |
| * be signaled) |
| * \retval C2_REFUSED no permission to wait for the fence (unexpected - system) |
| * \retval C2_CORRUPTED some unknown error prevented waiting for the fence (unexpected) |
| */ |
| c2_status_t wait(c2_nsecs_t timeoutNs); |
| |
| /** |
| * Used to check if this fence is valid (if there is a chance for it to be signaled.) |
| * A fence becomes invalid if the controling event is destroyed without it signaling the fence. |
| * |
| * \return whether this fence is valid |
| */ |
| bool valid() const; |
| |
| /** |
| * Used to check if this fence has been signaled (is ready). |
| * |
| * \return whether this fence has been signaled |
| */ |
| bool ready() const; |
| |
| /** |
| * Returns a file descriptor that can be used to wait for this fence in a select system call. |
| * \note The returned file descriptor, if valid, must be closed by the caller. |
| * |
| * This can be used in e.g. poll() system calls. This file becomes readable (POLLIN) when the |
| * fence is signaled, and bad (POLLERR) if the fence is abandoned. |
| * |
| * \return a file descriptor representing this fence (with ownership), or -1 if the fence |
| * has already been signaled (\todo or abandoned). |
| * |
| * \todo this must be compatible with fences used by gralloc |
| */ |
| int fd() const; |
| |
| /** |
| * Returns whether this fence is a hardware-backed fence. |
| * \return whether this is a hardware fence |
| */ |
| bool isHW() const; |
| |
| /** |
| * Null-fence. A fence that has fired. |
| */ |
| constexpr C2Fence() : mImpl(nullptr) { } |
| |
| private: |
| class Impl; |
| std::shared_ptr<Impl> mImpl; |
| C2Fence(std::shared_ptr<Impl> impl); |
| friend struct _C2FenceFactory; |
| }; |
| |
| /** |
| * Event object used by components and the framework. |
| * |
| * Implements the signaling of an event, analogous to a 'promise'. |
| * |
| * Hardware backed events do not go through this object, and must be exposed directly as fences |
| * by vendors. |
| */ |
| class C2Event { |
| public: |
| /** |
| * Returns a fence for this event. |
| */ |
| C2Fence fence() const; |
| |
| /** |
| * Signals (all) associated fence(s). |
| * This has no effect no effect if the event was already signaled or abandoned. |
| * |
| * \retval C2_OK the fence(s) were successfully signaled |
| * \retval C2_BAD_STATE the fence(s) have already been abandoned or merged (caller error) |
| * \retval C2_DUPLICATE the fence(s) have already been signaled (caller error) |
| * \retval C2_REFUSED no permission to signal the fence (unexpected - system) |
| * \retval C2_CORRUPTED some unknown error prevented signaling the fence(s) (unexpected) |
| */ |
| c2_status_t fire(); |
| |
| /** |
| * Trigger this event from the merging of the supplied fences. This means that it will be |
| * abandoned if any of these fences have been abandoned, and it will be fired if all of these |
| * fences have been signaled. |
| * |
| * \retval C2_OK the merging was successfully done |
| * \retval C2_NO_MEMORY not enough memory to perform the merging |
| * \retval C2_DUPLICATE the fence have already been merged (caller error) |
| * \retval C2_BAD_STATE the fence have already been signaled or abandoned (caller error) |
| * \retval C2_REFUSED no permission to merge the fence (unexpected - system) |
| * \retval C2_CORRUPTED some unknown error prevented merging the fence(s) (unexpected) |
| */ |
| c2_status_t merge(std::vector<C2Fence> fences); |
| |
| /** |
| * Abandons the event and any associated fence(s). |
| * \note Call this to explicitly abandon an event before it is destructed to avoid a warning. |
| * |
| * This has no effect no effect if the event was already signaled or abandoned. |
| * |
| * \retval C2_OK the fence(s) were successfully signaled |
| * \retval C2_BAD_STATE the fence(s) have already been signaled or merged (caller error) |
| * \retval C2_DUPLICATE the fence(s) have already been abandoned (caller error) |
| * \retval C2_REFUSED no permission to abandon the fence (unexpected - system) |
| * \retval C2_CORRUPTED some unknown error prevented signaling the fence(s) (unexpected) |
| */ |
| c2_status_t abandon(); |
| |
| private: |
| class Impl; |
| std::shared_ptr<Impl> mImpl; |
| }; |
| |
| /// \addtogroup buf_internal Internal |
| /// @{ |
| |
| /** |
| * Interface for objects that encapsulate an updatable status value. |
| */ |
| struct _C2InnateStatus { |
| inline c2_status_t status() const { return mStatus; } |
| |
| protected: |
| _C2InnateStatus(c2_status_t status) : mStatus(status) { } |
| |
| c2_status_t mStatus; // this status is updatable by the object |
| }; |
| |
| /// @} |
| |
| /** |
| * This is a utility template for objects protected by an acquire fence, so that errors during |
| * acquiring the object are propagated to the object itself. |
| */ |
| template<typename T> |
| class C2Acquirable : public C2Fence { |
| public: |
| /** |
| * Acquires the object protected by an acquire fence. Any errors during the mapping will be |
| * passed to the object. |
| * |
| * \return acquired object potentially invalidated if waiting for the fence failed. |
| */ |
| T get() { |
| // TODO: |
| // wait(); |
| return mT; |
| } |
| |
| protected: |
| C2Acquirable(c2_status_t error, C2Fence fence, T t) : C2Fence(fence), mInitialError(error), mT(t) { } |
| |
| private: |
| c2_status_t mInitialError; |
| T mT; // TODO: move instead of copy |
| }; |
| |
| /// @} |
| |
| /// \defgroup linear Linear Data Blocks |
| /// @{ |
| |
| /************************************************************************************************** |
| LINEAR ASPECTS, BLOCKS AND VIEWS |
| **************************************************************************************************/ |
| |
| /** |
| * Basic segment math support. |
| */ |
| struct C2Segment { |
| uint32_t offset; |
| uint32_t size; |
| |
| inline constexpr C2Segment(uint32_t offset_, uint32_t size_) |
| : offset(offset_), |
| size(size_) { |
| } |
| |
| inline constexpr bool isEmpty() const { |
| return size == 0; |
| } |
| |
| inline constexpr bool isValid() const { |
| return offset <= ~size; |
| } |
| |
| inline constexpr operator bool() const { |
| return isValid() && !isEmpty(); |
| } |
| |
| inline constexpr bool operator!() const { |
| return !bool(*this); |
| } |
| |
| C2_ALLOW_OVERFLOW |
| inline constexpr bool contains(const C2Segment &other) const { |
| if (!isValid() || !other.isValid()) { |
| return false; |
| } else { |
| return offset <= other.offset |
| && offset + size >= other.offset + other.size; |
| } |
| } |
| |
| inline constexpr bool operator==(const C2Segment &other) const { |
| if (!isValid()) { |
| return !other.isValid(); |
| } else { |
| return offset == other.offset && size == other.size; |
| } |
| } |
| |
| inline constexpr bool operator!=(const C2Segment &other) const { |
| return !operator==(other); |
| } |
| |
| inline constexpr bool operator>=(const C2Segment &other) const { |
| return contains(other); |
| } |
| |
| inline constexpr bool operator>(const C2Segment &other) const { |
| return contains(other) && !operator==(other); |
| } |
| |
| inline constexpr bool operator<=(const C2Segment &other) const { |
| return other.contains(*this); |
| } |
| |
| inline constexpr bool operator<(const C2Segment &other) const { |
| return other.contains(*this) && !operator==(other); |
| } |
| |
| C2_ALLOW_OVERFLOW |
| inline constexpr uint32_t end() const { |
| return offset + size; |
| } |
| |
| C2_ALLOW_OVERFLOW |
| inline constexpr C2Segment intersect(const C2Segment &other) const { |
| return C2Segment(c2_max(offset, other.offset), |
| c2_min(end(), other.end()) - c2_max(offset, other.offset)); |
| } |
| |
| /** clamps end to offset if it overflows */ |
| inline constexpr C2Segment normalize() const { |
| return C2Segment(offset, c2_max(offset, end()) - offset); |
| } |
| |
| /** clamps end to max if it overflows */ |
| inline constexpr C2Segment saturate() const { |
| return C2Segment(offset, c2_min(size, ~offset)); |
| } |
| |
| }; |
| |
| /** |
| * Common aspect for all objects that have a linear capacity. |
| */ |
| class _C2LinearCapacityAspect { |
| /// \name Linear capacity interface |
| /// @{ |
| public: |
| inline constexpr uint32_t capacity() const { return mCapacity; } |
| |
| inline constexpr operator C2Segment() const { |
| return C2Segment(0, mCapacity); |
| } |
| |
| protected: |
| |
| #if UINTPTR_MAX == 0xffffffff |
| static_assert(sizeof(size_t) == sizeof(uint32_t), "size_t is too big"); |
| #else |
| static_assert(sizeof(size_t) > sizeof(uint32_t), "size_t is too small"); |
| // explicitly disable construction from size_t |
| inline explicit _C2LinearCapacityAspect(size_t capacity) = delete; |
| #endif |
| |
| inline explicit constexpr _C2LinearCapacityAspect(uint32_t capacity) |
| : mCapacity(capacity) { } |
| |
| inline explicit constexpr _C2LinearCapacityAspect(const _C2LinearCapacityAspect *parent) |
| : mCapacity(parent == nullptr ? 0 : parent->capacity()) { } |
| |
| private: |
| uint32_t mCapacity; |
| /// @} |
| }; |
| |
| /** |
| * Aspect for objects that have a linear range inside a linear capacity. |
| * |
| * This class is copiable. |
| */ |
| class _C2LinearRangeAspect : public _C2LinearCapacityAspect { |
| /// \name Linear range interface |
| /// @{ |
| public: |
| inline constexpr uint32_t offset() const { return mOffset; } |
| inline constexpr uint32_t endOffset() const { return mOffset + mSize; } |
| inline constexpr uint32_t size() const { return mSize; } |
| |
| inline constexpr operator C2Segment() const { |
| return C2Segment(mOffset, mSize); |
| } |
| |
| private: |
| // subrange of capacity [0, capacity] & [size, size + offset] |
| inline constexpr _C2LinearRangeAspect(uint32_t capacity_, size_t offset, size_t size) |
| : _C2LinearCapacityAspect(capacity_), |
| mOffset(c2_min(offset, capacity())), |
| mSize(c2_min(size, capacity() - mOffset)) { |
| } |
| |
| protected: |
| // copy constructor (no error check) |
| inline constexpr _C2LinearRangeAspect(const _C2LinearRangeAspect &other) |
| : _C2LinearCapacityAspect(other.capacity()), |
| mOffset(other.offset()), |
| mSize(other.size()) { |
| } |
| |
| // parent capacity range [0, capacity] |
| inline constexpr explicit _C2LinearRangeAspect(const _C2LinearCapacityAspect *parent) |
| : _C2LinearCapacityAspect(parent), |
| mOffset(0), |
| mSize(capacity()) { |
| } |
| |
| // subrange of parent capacity [0, capacity] & [size, size + offset] |
| inline constexpr _C2LinearRangeAspect(const _C2LinearCapacityAspect *parent, size_t offset, size_t size) |
| : _C2LinearCapacityAspect(parent), |
| mOffset(c2_min(offset, capacity())), |
| mSize(c2_min(size, capacity() - mOffset)) { |
| } |
| |
| // subsection of the parent's and [offset, offset + size] ranges |
| inline constexpr _C2LinearRangeAspect(const _C2LinearRangeAspect *parent, size_t offset, size_t size) |
| : _C2LinearCapacityAspect(parent), |
| mOffset(c2_min(c2_max(offset, parent == nullptr ? 0 : parent->offset()), capacity())), |
| mSize(std::min(c2_min(size, parent == nullptr ? 0 : parent->size()), capacity() - mOffset)) { |
| } |
| |
| public: |
| inline constexpr _C2LinearRangeAspect childRange(size_t offset, size_t size) const { |
| return _C2LinearRangeAspect( |
| mSize, |
| c2_min(c2_max(offset, mOffset), capacity()) - mOffset, |
| c2_min(c2_min(size, mSize), capacity() - c2_min(c2_max(offset, mOffset), capacity()))); |
| } |
| |
| friend class _C2EditableLinearRangeAspect; |
| // invariants 0 <= mOffset <= mOffset + mSize <= capacity() |
| uint32_t mOffset; |
| uint32_t mSize; |
| /// @} |
| }; |
| |
| /** |
| * Utility class for safe range calculations using size_t-s. |
| */ |
| class C2LinearRange : public _C2LinearRangeAspect { |
| public: |
| inline constexpr C2LinearRange(const _C2LinearCapacityAspect &parent, size_t offset, size_t size) |
| : _C2LinearRangeAspect(&parent, offset, size) { } |
| |
| inline constexpr C2LinearRange(const _C2LinearRangeAspect &parent, size_t offset, size_t size) |
| : _C2LinearRangeAspect(&parent, offset, size) { } |
| |
| inline constexpr C2LinearRange intersect(size_t offset, size_t size) const { |
| return C2LinearRange(*this, offset, size); |
| } |
| }; |
| |
| /** |
| * Utility class for simple and safe capacity and range construction. |
| */ |
| class C2LinearCapacity : public _C2LinearCapacityAspect { |
| public: |
| inline constexpr explicit C2LinearCapacity(size_t capacity) |
| : _C2LinearCapacityAspect(c2_min(capacity, std::numeric_limits<uint32_t>::max())) { } |
| |
| inline constexpr C2LinearRange range(size_t offset, size_t size) const { |
| return C2LinearRange(*this, offset, size); |
| } |
| }; |
| |
| /** |
| * Aspect for objects that have an editable linear range. |
| * |
| * This class is copiable. |
| */ |
| class _C2EditableLinearRangeAspect : public _C2LinearRangeAspect { |
| using _C2LinearRangeAspect::_C2LinearRangeAspect; |
| |
| public: |
| /// \name Editable linear range interface |
| /// @{ |
| |
| /** |
| * Sets the offset to |offset|, while trying to keep the end of the buffer unchanged (e.g. |
| * size will grow if offset is decreased, and may shrink if offset is increased.) Returns |
| * true if successful, which is equivalent to if 0 <= |offset| <= capacity(). |
| * |
| * Note: setting offset and size will yield different result depending on the order of the |
| * operations. Always set offset first to ensure proper size. |
| */ |
| inline bool setOffset(uint32_t offset) { |
| if (offset > capacity()) { |
| return false; |
| } |
| |
| if (offset > mOffset + mSize) { |
| mSize = 0; |
| } else { |
| mSize = mOffset + mSize - offset; |
| } |
| mOffset = offset; |
| return true; |
| } |
| |
| /** |
| * Sets the size to |size|. Returns true if successful, which is equivalent to |
| * if 0 <= |size| <= capacity() - offset(). |
| * |
| * Note: setting offset and size will yield different result depending on the order of the |
| * operations. Always set offset first to ensure proper size. |
| */ |
| inline bool setSize(uint32_t size) { |
| if (size > capacity() - mOffset) { |
| return false; |
| } else { |
| mSize = size; |
| return true; |
| } |
| } |
| |
| /** |
| * Sets the offset to |offset| with best effort. Same as setOffset() except that offset will |
| * be clamped to the buffer capacity. |
| * |
| * Note: setting offset and size (even using best effort) will yield different result depending |
| * on the order of the operations. Always set offset first to ensure proper size. |
| */ |
| inline void setOffset_be(uint32_t offset) { |
| (void)setOffset(c2_min(offset, capacity())); |
| } |
| |
| /** |
| * Sets the size to |size| with best effort. Same as setSize() except that the selected region |
| * will be clamped to the buffer capacity (e.g. size is clamped to [0, capacity() - offset()]). |
| * |
| * Note: setting offset and size (even using best effort) will yield different result depending |
| * on the order of the operations. Always set offset first to ensure proper size. |
| */ |
| inline void setSize_be(uint32_t size) { |
| mSize = c2_min(size, capacity() - mOffset); |
| } |
| /// @} |
| }; |
| |
| /************************************************************************************************** |
| ALLOCATIONS |
| **************************************************************************************************/ |
| |
| /// \ingroup allocator Allocation and memory placement |
| /// @{ |
| |
| class C2LinearAllocation; |
| class C2GraphicAllocation; |
| |
| /** |
| * Allocators are used by the framework to allocate memory (allocations) for buffers. They can |
| * support either 1D or 2D allocations. |
| * |
| * \note In theory they could support both, but in practice, we will use only one or the other. |
| * |
| * Never constructed on stack. |
| * |
| * Allocators are provided by vendors. |
| */ |
| class C2Allocator { |
| public: |
| /** |
| * Allocator ID type. |
| */ |
| typedef uint32_t id_t; |
| enum : id_t { |
| BAD_ID = 0xBADD, // invalid allocator ID |
| }; |
| |
| /** |
| * Allocation types. This is a bitmask and is used in C2Allocator::Info |
| * to list the supported allocation types of an allocator. |
| */ |
| enum type_t : uint32_t { |
| LINEAR = 1 << 0, // |
| GRAPHIC = 1 << 1, |
| }; |
| |
| /** |
| * Information about an allocator. |
| * |
| * Allocators don't have a query API so all queriable information is stored here. |
| */ |
| struct Traits { |
| C2String name; ///< allocator name |
| id_t id; ///< allocator ID |
| type_t supportedTypes; ///< supported allocation types |
| C2MemoryUsage minimumUsage; ///< usage that is minimally required for allocations |
| C2MemoryUsage maximumUsage; ///< usage that is maximally allowed for allocations |
| }; |
| |
| /** |
| * Returns the unique name of this allocator. |
| * |
| * This method MUST be "non-blocking" and return within 1ms. |
| * |
| * \return the name of this allocator. |
| * \retval an empty string if there was not enough memory to allocate the actual name. |
| */ |
| virtual C2String getName() const = 0; |
| |
| /** |
| * Returns a unique ID for this allocator. This ID is used to get this allocator from the |
| * allocator store, and to identify this allocator across all processes. |
| * |
| * This method MUST be "non-blocking" and return within 1ms. |
| * |
| * \return a unique ID for this allocator. |
| */ |
| virtual id_t getId() const = 0; |
| |
| /** |
| * Returns the allocator traits. |
| * |
| * This method MUST be "non-blocking" and return within 1ms. |
| * |
| * Allocators don't have a full-fledged query API, only this method. |
| * |
| * \return allocator information |
| */ |
| virtual std::shared_ptr<const Traits> getTraits() const = 0; |
| |
| /** |
| * Allocates a 1D allocation of given |capacity| and |usage|. If successful, the allocation is |
| * stored in |allocation|. Otherwise, |allocation| is set to 'nullptr'. |
| * |
| * \param capacity the size of requested allocation (the allocation could be slightly |
| * larger, e.g. to account for any system-required alignment) |
| * \param usage the memory usage info for the requested allocation. \note that the |
| * returned allocation may be later used/mapped with different usage. |
| * The allocator should layout the buffer to be optimized for this usage, |
| * but must support any usage. One exception: protected buffers can |
| * only be used in a protected scenario. |
| * \param allocation pointer to where the allocation shall be stored on success. nullptr |
| * will be stored here on failure |
| * |
| * \retval C2_OK the allocation was successful |
| * \retval C2_NO_MEMORY not enough memory to complete the allocation |
| * \retval C2_TIMED_OUT the allocation timed out |
| * \retval C2_REFUSED no permission to complete the allocation |
| * \retval C2_BAD_VALUE capacity or usage are not supported (invalid) (caller error) |
| * \retval C2_OMITTED this allocator does not support 1D allocations |
| * \retval C2_CORRUPTED some unknown, unrecoverable error occured during allocation (unexpected) |
| */ |
| virtual c2_status_t newLinearAllocation( |
| uint32_t capacity __unused, C2MemoryUsage usage __unused, |
| std::shared_ptr<C2LinearAllocation> *allocation /* nonnull */) { |
| *allocation = nullptr; |
| return C2_OMITTED; |
| } |
| |
| /** |
| * (Re)creates a 1D allocation from a native |handle|. If successful, the allocation is stored |
| * in |allocation|. Otherwise, |allocation| is set to 'nullptr'. |
| * |
| * \param handle the handle for the existing allocation. On success, the allocation will |
| * take ownership of |handle|. |
| * \param allocation pointer to where the allocation shall be stored on success. nullptr |
| * will be stored here on failure |
| * |
| * \retval C2_OK the allocation was recreated successfully |
| * \retval C2_NO_MEMORY not enough memory to recreate the allocation |
| * \retval C2_TIMED_OUT the recreation timed out (unexpected) |
| * \retval C2_REFUSED no permission to recreate the allocation |
| * \retval C2_BAD_VALUE invalid handle (caller error) |
| * \retval C2_OMITTED this allocator does not support 1D allocations |
| * \retval C2_CORRUPTED some unknown, unrecoverable error occured during allocation (unexpected) |
| */ |
| virtual c2_status_t priorLinearAllocation( |
| const C2Handle *handle __unused, |
| std::shared_ptr<C2LinearAllocation> *allocation /* nonnull */) { |
| *allocation = nullptr; |
| return C2_OMITTED; |
| } |
| |
| /** |
| * Allocates a 2D allocation of given |width|, |height|, |format| and |usage|. If successful, |
| * the allocation is stored in |allocation|. Otherwise, |allocation| is set to 'nullptr'. |
| * |
| * \param width the width of requested allocation (the allocation could be slightly |
| * larger, e.g. to account for any system-required alignment) |
| * \param height the height of requested allocation (the allocation could be slightly |
| * larger, e.g. to account for any system-required alignment) |
| * \param format the pixel format of requested allocation. This could be a vendor |
| * specific format. |
| * \param usage the memory usage info for the requested allocation. \note that the |
| * returned allocation may be later used/mapped with different usage. |
| * The allocator should layout the buffer to be optimized for this usage, |
| * but must support any usage. One exception: protected buffers can |
| * only be used in a protected scenario. |
| * \param allocation pointer to where the allocation shall be stored on success. nullptr |
| * will be stored here on failure |
| * |
| * \retval C2_OK the allocation was successful |
| * \retval C2_NO_MEMORY not enough memory to complete the allocation |
| * \retval C2_TIMED_OUT the allocation timed out |
| * \retval C2_REFUSED no permission to complete the allocation |
| * \retval C2_BAD_VALUE width, height, format or usage are not supported (invalid) (caller error) |
| * \retval C2_OMITTED this allocator does not support 2D allocations |
| * \retval C2_CORRUPTED some unknown, unrecoverable error occured during allocation (unexpected) |
| */ |
| virtual c2_status_t newGraphicAllocation( |
| uint32_t width __unused, uint32_t height __unused, uint32_t format __unused, |
| C2MemoryUsage usage __unused, |
| std::shared_ptr<C2GraphicAllocation> *allocation /* nonnull */) { |
| *allocation = nullptr; |
| return C2_OMITTED; |
| } |
| |
| /** |
| * (Re)creates a 2D allocation from a native handle. If successful, the allocation is stored |
| * in |allocation|. Otherwise, |allocation| is set to 'nullptr'. |
| * |
| * \param handle the handle for the existing allocation. On success, the allocation will |
| * take ownership of |handle|. |
| * \param allocation pointer to where the allocation shall be stored on success. nullptr |
| * will be stored here on failure |
| * |
| * \retval C2_OK the allocation was recreated successfully |
| * \retval C2_NO_MEMORY not enough memory to recreate the allocation |
| * \retval C2_TIMED_OUT the recreation timed out (unexpected) |
| * \retval C2_REFUSED no permission to recreate the allocation |
| * \retval C2_BAD_VALUE invalid handle (caller error) |
| * \retval C2_OMITTED this allocator does not support 2D allocations |
| * \retval C2_CORRUPTED some unknown, unrecoverable error occured during recreation (unexpected) |
| */ |
| virtual c2_status_t priorGraphicAllocation( |
| const C2Handle *handle __unused, |
| std::shared_ptr<C2GraphicAllocation> *allocation /* nonnull */) { |
| *allocation = nullptr; |
| return C2_OMITTED; |
| } |
| |
| virtual ~C2Allocator() = default; |
| protected: |
| C2Allocator() = default; |
| }; |
| |
| /** |
| * \ingroup linear allocator |
| * 1D allocation interface. |
| */ |
| class C2LinearAllocation : public _C2LinearCapacityAspect { |
| public: |
| /** |
| * Maps a portion of an allocation starting from |offset| with |size| into local process memory. |
| * Stores the starting address into |addr|, or NULL if the operation was unsuccessful. |
| * |fence| will contain an acquire sync fence object. If it is already |
| * safe to access the buffer contents, then it will contain an empty (already fired) fence. |
| * |
| * \param offset starting position of the portion to be mapped (this does not have to |
| * be page aligned) |
| * \param size size of the portion to be mapped (this does not have to be page |
| * aligned) |
| * \param usage the desired usage. \todo this must be kSoftwareRead and/or |
| * kSoftwareWrite. |
| * \param fence a pointer to a fence object if an async mapping is requested. If |
| * not-null, and acquire fence will be stored here on success, or empty |
| * fence on failure. If null, the mapping will be synchronous. |
| * \param addr a pointer to where the starting address of the mapped portion will be |
| * stored. On failure, nullptr will be stored here. |
| * |
| * \todo Only one portion can be mapped at the same time - this is true for gralloc, but there |
| * is no need for this for 1D buffers. |
| * \todo Do we need to support sync operation as we could just wait for the fence? |
| * |
| * \retval C2_OK the operation was successful |
| * \retval C2_REFUSED no permission to map the portion |
| * \retval C2_TIMED_OUT the operation timed out |
| * \retval C2_DUPLICATE if the allocation is already mapped. |
| * \retval C2_NO_MEMORY not enough memory to complete the operation |
| * \retval C2_BAD_VALUE the parameters (offset/size) are invalid or outside the allocation, or |
| * the usage flags are invalid (caller error) |
| * \retval C2_CORRUPTED some unknown error prevented the operation from completing (unexpected) |
| */ |
| virtual c2_status_t map( |
| size_t offset, size_t size, C2MemoryUsage usage, C2Fence *fence /* nullable */, |
| void **addr /* nonnull */) = 0; |
| |
| /** |
| * Unmaps a portion of an allocation at |addr| with |size|. These must be parameters previously |
| * passed to and returned by |map|; otherwise, this operation is a no-op. |
| * |
| * \param addr starting address of the mapped region |
| * \param size size of the mapped region |
| * \param fence a pointer to a fence object if an async unmapping is requested. If |
| * not-null, a release fence will be stored here on success, or empty fence |
| * on failure. This fence signals when the original allocation contains |
| * all changes that happened to the mapped region. If null, the unmapping |
| * will be synchronous. |
| * |
| * \retval C2_OK the operation was successful |
| * \retval C2_TIMED_OUT the operation timed out |
| * \retval C2_NOT_FOUND if the allocation was not mapped previously. |
| * \retval C2_BAD_VALUE the parameters (addr/size) do not correspond to previously mapped |
| * regions (caller error) |
| * \retval C2_CORRUPTED some unknown error prevented the operation from completing (unexpected) |
| * \retval C2_REFUSED no permission to unmap the portion (unexpected - system) |
| */ |
| virtual c2_status_t unmap(void *addr, size_t size, C2Fence *fence /* nullable */) = 0; |
| |
| /** |
| * Returns the allocator ID for this allocation. This is useful to put the handle into context. |
| */ |
| virtual C2Allocator::id_t getAllocatorId() const = 0; |
| |
| /** |
| * Returns a pointer to the allocation handle. |
| */ |
| virtual const C2Handle *handle() const = 0; |
| |
| /** |
| * Returns true if this is the same allocation as |other|. |
| */ |
| virtual bool equals(const std::shared_ptr<C2LinearAllocation> &other) const = 0; |
| |
| protected: |
| // \todo should we limit allocation directly? |
| C2LinearAllocation(size_t capacity) : _C2LinearCapacityAspect(c2_min(capacity, UINT32_MAX)) {} |
| virtual ~C2LinearAllocation() = default; |
| }; |
| |
| class C2CircularBlock; |
| class C2LinearBlock; |
| class C2GraphicBlock; |
| |
| /** |
| * Block pools are used by components to obtain output buffers in an efficient way. They can |
| * support either linear (1D), circular (1D) or graphic (2D) blocks. |
| * |
| * Block pools decouple the recycling of memory/allocations from the components. They are meant to |
| * be an opaque service (there are no public APIs other than obtaining blocks) provided by the |
| * platform. Block pools are also meant to decouple allocations from memory used by buffers. This |
| * is accomplished by allowing pools to allot multiple memory 'blocks' on a single allocation. As |
| * their name suggest, block pools maintain a pool of memory blocks. When a component asks for |
| * a memory block, pools will try to return a free memory block already in the pool. If no such |
| * block exists, they will allocate memory using the backing allocator and allot a block on that |
| * allocation. When blocks are no longer used in the system, they are recycled back to the block |
| * pool and are available as free blocks. |
| * |
| * Never constructed on stack. |
| */ |
| class C2BlockPool { |
| public: |
| /** |
| * Block pool ID type. |
| */ |
| typedef uint64_t local_id_t; |
| |
| enum : local_id_t { |
| BASIC_LINEAR = 0, ///< ID of basic (unoptimized) block pool for fetching 1D blocks |
| BASIC_GRAPHIC = 1, ///< ID of basic (unoptimized) block pool for fetching 2D blocks |
| PLATFORM_START = 0x10, |
| }; |
| |
| /** |
| * Returns the ID for this block pool. This ID is used to get this block pool from the platform. |
| * It is only valid in the current process. |
| * |
| * This method MUST be "non-blocking" and return within 1ms. |
| * |
| * \return a local ID for this block pool. |
| */ |
| virtual local_id_t getLocalId() const = 0; |
| |
| /** |
| * Returns the ID of the backing allocator of this block pool. |
| * |
| * This method MUST be "non-blocking" and return within 1ms. |
| * |
| * \return the ID of the backing allocator of this block pool. |
| */ |
| virtual C2Allocator::id_t getAllocatorId() const = 0; |
| |
| /** |
| * Obtains a linear writeable block of given |capacity| and |usage|. If successful, the |
| * block is stored in |block|. Otherwise, |block| is set to 'nullptr'. |
| * |
| * \param capacity the size of requested block. |
| * \param usage the memory usage info for the requested block. Returned blocks will be |
| * optimized for this usage, but may be used with any usage. One exception: |
| * protected blocks/buffers can only be used in a protected scenario. |
| * \param block pointer to where the obtained block shall be stored on success. nullptr will |
| * be stored here on failure |
| * |
| * \retval C2_OK the operation was successful |
| * \retval C2_NO_MEMORY not enough memory to complete any required allocation |
| * \retval C2_TIMED_OUT the operation timed out |
| * \retval C2_BLOCKING the operation is blocked |
| * \retval C2_REFUSED no permission to complete any required allocation |
| * \retval C2_BAD_VALUE capacity or usage are not supported (invalid) (caller error) |
| * \retval C2_OMITTED this pool does not support linear blocks |
| * \retval C2_CORRUPTED some unknown, unrecoverable error occured during operation (unexpected) |
| */ |
| virtual c2_status_t fetchLinearBlock( |
| uint32_t capacity __unused, C2MemoryUsage usage __unused, |
| std::shared_ptr<C2LinearBlock> *block /* nonnull */) { |
| *block = nullptr; |
| return C2_OMITTED; |
| } |
| |
| /** |
| * Obtains a circular writeable block of given |capacity| and |usage|. If successful, the |
| * block is stored in |block|. Otherwise, |block| is set to 'nullptr'. |
| * |
| * \param capacity the size of requested circular block. (note: the size of the obtained |
| * block could be slightly larger, e.g. to accommodate any system-required |
| * alignment) |
| * \param usage the memory usage info for the requested block. Returned blocks will be |
| * optimized for this usage, but may be used with any usage. One exception: |
| * protected blocks/buffers can only be used in a protected scenario. |
| * \param block pointer to where the obtained block shall be stored on success. nullptr |
| * will be stored here on failure |
| * |
| * \retval C2_OK the operation was successful |
| * \retval C2_NO_MEMORY not enough memory to complete any required allocation |
| * \retval C2_TIMED_OUT the operation timed out |
| * \retval C2_BLOCKING the operation is blocked |
| * \retval C2_REFUSED no permission to complete any required allocation |
| * \retval C2_BAD_VALUE capacity or usage are not supported (invalid) (caller error) |
| * \retval C2_OMITTED this pool does not support circular blocks |
| * \retval C2_CORRUPTED some unknown, unrecoverable error occured during operation (unexpected) |
| */ |
| virtual c2_status_t fetchCircularBlock( |
| uint32_t capacity __unused, C2MemoryUsage usage __unused, |
| std::shared_ptr<C2CircularBlock> *block /* nonnull */) { |
| *block = nullptr; |
| return C2_OMITTED; |
| } |
| |
| /** |
| * Obtains a 2D graphic block of given |width|, |height|, |format| and |usage|. If successful, |
| * the block is stored in |block|. Otherwise, |block| is set to 'nullptr'. |
| * |
| * \param width the width of requested block (the obtained block could be slightly larger, e.g. |
| * to accommodate any system-required alignment) |
| * \param height the height of requested block (the obtained block could be slightly larger, |
| * e.g. to accommodate any system-required alignment) |
| * \param format the pixel format of requested block. This could be a vendor specific format. |
| * \param usage the memory usage info for the requested block. Returned blocks will be |
| * optimized for this usage, but may be used with any usage. One exception: |
| * protected blocks/buffers can only be used in a protected scenario. |
| * \param block pointer to where the obtained block shall be stored on success. nullptr |
| * will be stored here on failure |
| * |
| * \retval C2_OK the operation was successful |
| * \retval C2_NO_MEMORY not enough memory to complete any required allocation |
| * \retval C2_TIMED_OUT the operation timed out |
| * \retval C2_BLOCKING the operation is blocked |
| * \retval C2_REFUSED no permission to complete any required allocation |
| * \retval C2_BAD_VALUE width, height, format or usage are not supported (invalid) (caller |
| * error) |
| * \retval C2_OMITTED this pool does not support 2D blocks |
| * \retval C2_CORRUPTED some unknown, unrecoverable error occured during operation (unexpected) |
| */ |
| virtual c2_status_t fetchGraphicBlock( |
| uint32_t width __unused, uint32_t height __unused, uint32_t format __unused, |
| C2MemoryUsage usage __unused, |
| std::shared_ptr<C2GraphicBlock> *block /* nonnull */) { |
| *block = nullptr; |
| return C2_OMITTED; |
| } |
| |
| virtual ~C2BlockPool() = default; |
| protected: |
| C2BlockPool() = default; |
| }; |
| |
| /// @} |
| |
| // ================================================================================================ |
| // BLOCKS |
| // ================================================================================================ |
| |
| /** |
| * Blocks are sections of allocations. They can be either 1D or 2D. |
| */ |
| |
| class C2LinearAllocation; |
| |
| /** |
| * A 1D block. |
| * |
| * \note capacity() is not meaningful for users of blocks; instead size() is the capacity of the |
| * usable portion. Use and offset() and size() if accessing the block directly through its handle |
| * to represent the allotted range of the underlying allocation to this block. |
| */ |
| class C2Block1D : public _C2LinearRangeAspect { |
| public: |
| /** |
| * Returns the underlying handle for this allocation. |
| * |
| * \note that the block and its block pool has shared ownership of the handle |
| * and if all references to the block are released, the underlying block |
| * allocation may get reused even if a client keeps a clone of this handle. |
| */ |
| const C2Handle *handle() const; |
| |
| /** |
| * Returns the allocator's ID that created the underlying allocation for this block. This |
| * provides the context for understanding the handle. |
| */ |
| C2Allocator::id_t getAllocatorId() const; |
| |
| protected: |
| class Impl; |
| /** construct a block. */ |
| C2Block1D(std::shared_ptr<Impl> impl, const _C2LinearRangeAspect &range); |
| |
| friend struct _C2BlockFactory; |
| std::shared_ptr<Impl> mImpl; |
| }; |
| |
| /** |
| * Read view provides read-only access for a linear memory segment. |
| * |
| * This class is copiable. |
| */ |
| class C2ReadView : public _C2LinearCapacityAspect { |
| public: |
| /** |
| * \return pointer to the start of the block or nullptr on error. |
| * This pointer is only valid during the lifetime of this view or until it is released. |
| */ |
| const uint8_t *data() const; |
| |
| /** |
| * Returns a portion of this view. |
| * |
| * \param offset the start offset of the portion. \note This is clamped to the capacity of this |
| * view. |
| * \param size the size of the portion. \note This is clamped to the remaining data from offset. |
| * |
| * \return a read view containing a portion of this view |
| */ |
| C2ReadView subView(size_t offset, size_t size) const; |
| |
| /** |
| * \return error during the creation/mapping of this view. |
| */ |
| c2_status_t error() const; |
| |
| /** |
| * Releases this view. This sets error to C2_NO_INIT. |
| */ |
| //void release(); |
| |
| protected: |
| class Impl; |
| C2ReadView(std::shared_ptr<Impl> impl, uint32_t offset, uint32_t size); |
| explicit C2ReadView(c2_status_t error); |
| |
| private: |
| friend struct _C2BlockFactory; |
| std::shared_ptr<Impl> mImpl; |
| uint32_t mOffset; /**< offset into the linear block backing this read view */ |
| }; |
| |
| /** |
| * Write view provides read/write access for a linear memory segment. |
| * |
| * This class is copiable. \todo movable only? |
| */ |
| class C2WriteView : public _C2EditableLinearRangeAspect { |
| public: |
| /** |
| * Start of the block. |
| * |
| * \return pointer to the start of the block or nullptr on error. |
| * This pointer is only valid during the lifetime of this view or until it is released. |
| */ |
| uint8_t *base(); |
| |
| /** |
| * \return pointer to the block at the current offset or nullptr on error. |
| * This pointer is only valid during the lifetime of this view or until it is released. |
| */ |
| uint8_t *data(); |
| |
| /** |
| * \return error during the creation/mapping of this view. |
| */ |
| c2_status_t error() const; |
| |
| /** |
| * Releases this view. This sets error to C2_NO_INIT. |
| */ |
| //void release(); |
| |
| protected: |
| class Impl; |
| C2WriteView(std::shared_ptr<Impl> impl); |
| explicit C2WriteView(c2_status_t error); |
| |
| private: |
| friend struct _C2BlockFactory; |
| std::shared_ptr<Impl> mImpl; |
| }; |
| |
| /** |
| * A constant (read-only) linear block (portion of an allocation) with an acquire fence. |
| * Blocks are unmapped when created, and can be mapped into a read view on demand. |
| * |
| * This class is copiable and contains a reference to the allocation that it is based on. |
| */ |
| class C2ConstLinearBlock : public C2Block1D { |
| public: |
| /** |
| * Maps this block into memory and returns a read view for it. |
| * |
| * \return a read view for this block. |
| */ |
| C2Acquirable<C2ReadView> map() const; |
| |
| /** |
| * Returns a portion of this block. |
| * |
| * \param offset the start offset of the portion. \note This is clamped to the capacity of this |
| * block. |
| * \param size the size of the portion. \note This is clamped to the remaining data from offset. |
| * |
| * \return a constant linear block containing a portion of this block |
| */ |
| C2ConstLinearBlock subBlock(size_t offset, size_t size) const; |
| |
| /** |
| * Returns the acquire fence for this block. |
| * |
| * \return a fence that must be waited on before reading the block. |
| */ |
| C2Fence fence() const { return mFence; } |
| |
| protected: |
| C2ConstLinearBlock(std::shared_ptr<Impl> impl, const _C2LinearRangeAspect &range, C2Fence mFence); |
| |
| private: |
| friend struct _C2BlockFactory; |
| C2Fence mFence; |
| }; |
| |
| /** |
| * Linear block is a writeable 1D block. Once written, it can be shared in whole or in parts with |
| * consumers/readers as read-only const linear block(s). |
| */ |
| class C2LinearBlock : public C2Block1D { |
| public: |
| /** |
| * Maps this block into memory and returns a write view for it. |
| * |
| * \return a write view for this block. |
| */ |
| C2Acquirable<C2WriteView> map(); |
| |
| /** |
| * Creates a read-only const linear block for a portion of this block; optionally protected |
| * by an acquire fence. There are two ways to use this: |
| * |
| * 1) share ready block after writing data into the block. In this case no fence shall be |
| * supplied, and the block shall not be modified after calling this method. |
| * 2) share block metadata before actually (finishing) writing the data into the block. In |
| * this case a fence must be supplied that will be triggered when the data is written. |
| * The block shall be modified only until firing the event for the fence. |
| */ |
| C2ConstLinearBlock share(size_t offset, size_t size, C2Fence fence); |
| |
| protected: |
| C2LinearBlock(std::shared_ptr<Impl> impl, const _C2LinearRangeAspect &range); |
| |
| friend struct _C2BlockFactory; |
| }; |
| |
| /// @} |
| |
| /************************************************************************************************** |
| CIRCULAR BLOCKS AND VIEWS |
| **************************************************************************************************/ |
| |
| /// \defgroup circular Circular buffer support |
| /// @{ |
| |
| /** |
| * Circular blocks can be used to share data between a writer and a reader (and/or other consumers)- |
| * in a memory-efficient way by reusing a section of memory. Circular blocks are a bit more complex |
| * than single reader/single writer schemes to facilitate block-based consuming of data. |
| * |
| * They can operate in two modes: |
| * |
| * 1) one writer that creates blocks to be consumed (this model can be used by components) |
| * |
| * 2) one writer that writes continuously, and one reader that can creates blocks to be consumed |
| * by further recipients (this model is used by the framework, and cannot be used by components.) |
| * |
| * Circular blocks have four segments with running pointers: |
| * - reserved: data reserved and available for the writer |
| * - committed: data committed by the writer and available to the reader (if present) |
| * - used: data used by consumers (if present) |
| * - available: unused data available to be reserved |
| */ |
| class C2CircularBlock : public C2Block1D { |
| // TODO: add methods |
| |
| private: |
| size_t mReserved __unused; // end of reserved section |
| size_t mCommitted __unused; // end of committed section |
| size_t mUsed __unused; // end of used section |
| size_t mFree __unused; // end of free section |
| }; |
| |
| class _C2CircularBlockSegment : public _C2LinearCapacityAspect { |
| public: |
| /** |
| * Returns the available size for this segment. |
| * |
| * \return currently available size for this segment |
| */ |
| size_t available() const; |
| |
| /** |
| * Reserve some space for this segment from its current start. |
| * |
| * \param size desired space in bytes |
| * \param fence a pointer to an acquire fence. If non-null, the reservation is asynchronous and |
| * a fence will be stored here that will be signaled when the reservation is |
| * complete. If null, the reservation is synchronous. |
| * |
| * \retval C2_OK the space was successfully reserved |
| * \retval C2_NO_MEMORY the space requested cannot be reserved |
| * \retval C2_TIMED_OUT the reservation timed out \todo when? |
| * \retval C2_CORRUPTED some unknown error prevented reserving space. (unexpected) |
| */ |
| c2_status_t reserve(size_t size, C2Fence *fence /* nullable */); |
| |
| /** |
| * Abandons a portion of this segment. This will move to the beginning of this segment. |
| * |
| * \note This methods is only allowed if this segment is producing blocks. |
| * |
| * \param size number of bytes to abandon |
| * |
| * \retval C2_OK the data was successfully abandoned |
| * \retval C2_TIMED_OUT the operation timed out (unexpected) |
| * \retval C2_CORRUPTED some unknown error prevented abandoning the data (unexpected) |
| */ |
| c2_status_t abandon(size_t size); |
| |
| /** |
| * Share a portion as block(s) with consumers (these are moved to the used section). |
| * |
| * \note This methods is only allowed if this segment is producing blocks. |
| * \note Share does not move the beginning of the segment. (\todo add abandon/offset?) |
| * |
| * \param size number of bytes to share |
| * \param fence fence to be used for the section |
| * \param blocks vector where the blocks of the section are appended to |
| * |
| * \retval C2_OK the portion was successfully shared |
| * \retval C2_NO_MEMORY not enough memory to share the portion |
| * \retval C2_TIMED_OUT the operation timed out (unexpected) |
| * \retval C2_CORRUPTED some unknown error prevented sharing the data (unexpected) |
| */ |
| c2_status_t share(size_t size, C2Fence fence, std::vector<C2ConstLinearBlock> &blocks); |
| |
| /** |
| * Returns the beginning offset of this segment from the start of this circular block. |
| * |
| * @return beginning offset |
| */ |
| size_t begin(); |
| |
| /** |
| * Returns the end offset of this segment from the start of this circular block. |
| * |
| * @return end offset |
| */ |
| size_t end(); |
| }; |
| |
| /** |
| * A circular write-view is a dynamic mapped view for a segment of a circular block. Care must be |
| * taken when using this view so that only the section owned by the segment is modified. |
| */ |
| class C2CircularWriteView : public _C2LinearCapacityAspect { |
| public: |
| /** |
| * Start of the circular block. |
| * \note the segment does not own this pointer. |
| * |
| * \return pointer to the start of the circular block or nullptr on error. |
| */ |
| uint8_t *base(); |
| |
| /** |
| * \return error during the creation/mapping of this view. |
| */ |
| c2_status_t error() const; |
| }; |
| |
| /** |
| * The writer of a circular buffer. |
| * |
| * Can commit data to a reader (not supported for components) OR share data blocks directly with a |
| * consumer. |
| * |
| * If a component supports outputting data into circular buffers, it must allocate a circular |
| * block and use a circular writer. |
| */ |
| class C2CircularWriter : public _C2CircularBlockSegment { |
| public: |
| /** |
| * Commits a portion of this segment to the next segment. This moves the beginning of the |
| * segment. |
| * |
| * \param size number of bytes to commit to the next segment |
| * \param fence fence used for the commit (the fence must signal before the data is committed) |
| */ |
| c2_status_t commit(size_t size, C2Fence fence); |
| |
| /** |
| * Maps this block into memory and returns a write view for it. |
| * |
| * \return a write view for this block. |
| */ |
| C2Acquirable<C2CircularWriteView> map(); |
| }; |
| |
| /// @} |
| |
| /// \defgroup graphic Graphic Data Blocks |
| /// @{ |
| |
| /** |
| * C2Rect: rectangle type with non-negative coordinates. |
| * |
| * \note This struct has public fields without getters/setters. All methods are inline. |
| */ |
| struct C2Rect { |
| // public: |
| uint32_t width; |
| uint32_t height; |
| uint32_t left; |
| uint32_t top; |
| |
| constexpr inline C2Rect() |
| : C2Rect(0, 0, 0, 0) { } |
| |
| constexpr inline C2Rect(uint32_t width_, uint32_t height_) |
| : C2Rect(width_, height_, 0, 0) { } |
| |
| constexpr C2Rect inline at(uint32_t left_, uint32_t top_) const { |
| return C2Rect(width, height, left_, top_); |
| } |
| |
| // utility methods |
| |
| inline constexpr bool isEmpty() const { |
| return width == 0 || height == 0; |
| } |
| |
| inline constexpr bool isValid() const { |
| return left <= ~width && top <= ~height; |
| } |
| |
| inline constexpr operator bool() const { |
| return isValid() && !isEmpty(); |
| } |
| |
| inline constexpr bool operator!() const { |
| return !bool(*this); |
| } |
| |
| C2_ALLOW_OVERFLOW |
| inline constexpr bool contains(const C2Rect &other) const { |
| if (!isValid() || !other.isValid()) { |
| return false; |
| } else { |
| return left <= other.left && top <= other.top |
| && left + width >= other.left + other.width |
| && top + height >= other.top + other.height; |
| } |
| } |
| |
| inline constexpr bool operator==(const C2Rect &other) const { |
| if (!isValid()) { |
| return !other.isValid(); |
| } else { |
| return left == other.left && top == other.top |
| && width == other.width && height == other.height; |
| } |
| } |
| |
| inline constexpr bool operator!=(const C2Rect &other) const { |
| return !operator==(other); |
| } |
| |
| inline constexpr bool operator>=(const C2Rect &other) const { |
| return contains(other); |
| } |
| |
| inline constexpr bool operator>(const C2Rect &other) const { |
| return contains(other) && !operator==(other); |
| } |
| |
| inline constexpr bool operator<=(const C2Rect &other) const { |
| return other.contains(*this); |
| } |
| |
| inline constexpr bool operator<(const C2Rect &other) const { |
| return other.contains(*this) && !operator==(other); |
| } |
| |
| C2_ALLOW_OVERFLOW |
| inline constexpr uint32_t right() const { |
| return left + width; |
| } |
| |
| C2_ALLOW_OVERFLOW |
| inline constexpr uint32_t bottom() const { |
| return top + height; |
| } |
| |
| C2_ALLOW_OVERFLOW |
| inline constexpr C2Rect intersect(const C2Rect &other) const { |
| return C2Rect(c2_min(right(), other.right()) - c2_max(left, other.left), |
| c2_min(bottom(), other.bottom()) - c2_max(top, other.top), |
| c2_max(left, other.left), |
| c2_max(top, other.top)); |
| } |
| |
| /** clamps right and bottom to top, left if they overflow */ |
| inline constexpr C2Rect normalize() const { |
| return C2Rect(c2_max(left, right()) - left, c2_max(top, bottom()) - top, left, top); |
| } |
| |
| private: |
| /// note: potentially unusual argument order |
| constexpr inline C2Rect(uint32_t width_, uint32_t height_, uint32_t left_, uint32_t top_) |
| : width(width_), |
| height(height_), |
| left(left_), |
| top(top_) { } |
| }; |
| |
| /** |
| * Interface for objects that have a width and height (planar capacity). |
| */ |
| class _C2PlanarCapacityAspect { |
| /// \name Planar capacity interface |
| /// @{ |
| public: |
| inline constexpr uint32_t width() const { return _mWidth; } |
| inline constexpr uint32_t height() const { return _mHeight; } |
| |
| inline constexpr operator C2Rect() const { |
| return C2Rect(_mWidth, _mHeight); |
| } |
| |
| protected: |
| inline constexpr _C2PlanarCapacityAspect(uint32_t width, uint32_t height) |
| : _mWidth(width), _mHeight(height) { } |
| |
| inline explicit constexpr _C2PlanarCapacityAspect(const _C2PlanarCapacityAspect *parent) |
| : _mWidth(parent == nullptr ? 0 : parent->width()), |
| _mHeight(parent == nullptr ? 0 : parent->height()) { } |
| |
| private: |
| uint32_t _mWidth; |
| uint32_t _mHeight; |
| /// @} |
| }; |
| |
| /** |
| * C2PlaneInfo: information on the layout of a singe flexible plane. |
| * |
| * Public fields without getters/setters. |
| */ |
| struct C2PlaneInfo { |
| //public: |
| enum channel_t : uint32_t { |
| CHANNEL_Y, ///< luma |
| CHANNEL_R, ///< red |
| CHANNEL_G, ///< green |
| CHANNEL_B, ///< blue |
| CHANNEL_A, ///< alpha |
| CHANNEL_CR, ///< Cr |
| CHANNEL_CB, ///< Cb |
| } channel; |
| |
| int32_t colInc; ///< column increment in bytes. may be negative |
| int32_t rowInc; ///< row increment in bytes. may be negative |
| |
| uint32_t colSampling; ///< subsampling compared to width (must be a power of 2) |
| uint32_t rowSampling; ///< subsampling compared to height (must be a power of 2) |
| |
| uint32_t allocatedDepth; ///< size of each sample (must be a multiple of 8) |
| uint32_t bitDepth; ///< significant bits per sample |
| /** |
| * the right shift of the significant bits in the sample. E.g. if a 10-bit significant |
| * value is laid out in a 16-bit allocation aligned to LSB (values 0-1023), rightShift |
| * would be 0 as the 16-bit value read from the sample does not need to be right shifted |
| * and can be used as is (after applying a 10-bit mask of 0x3FF). |
| * |
| * +--------+--------+ |
| * | VV|VVVVVVVV| |
| * +--------+--------+ |
| * 15 8 7 0 |
| * |
| * If the value is laid out aligned to MSB, rightShift would be 6, as the value read |
| * from the allocated sample must be right-shifted by 6 to get the actual sample value. |
| * |
| * +--------+--------+ |
| * |VVVVVVVV|VV | |
| * +--------+--------+ |
| * 15 8 7 0 |
| */ |
| uint32_t rightShift; |
| |
| enum endianness_t : uint32_t { |
| NATIVE, |
| LITTLE_END, // LITTLE_ENDIAN is reserved macro |
| BIG_END, // BIG_ENDIAN is a reserved macro |
| } endianness; ///< endianness of the samples |
| |
| /** |
| * The following two fields define the relation between multiple planes. If multiple planes are |
| * interleaved, they share a root plane (whichever plane's start address is the lowest), and |
| * |offset| is the offset of this plane inside the root plane (in bytes). |rootIx| is the index |
| * of the root plane. If a plane is independent, rootIx is its index and offset is 0. |
| */ |
| uint32_t rootIx; ///< index of the root plane |
| uint32_t offset; ///< offset of this plane inside of the root plane |
| |
| inline constexpr ssize_t minOffset(uint32_t width, uint32_t height) const { |
| ssize_t offs = 0; |
| if (width > 0 && colInc < 0) { |
| offs += colInc * (ssize_t)(width - 1); |
| } |
| if (height > 0 && rowInc < 0) { |
| offs += rowInc * (ssize_t)(height - 1); |
| } |
| return offs; |
| } |
| |
| inline constexpr ssize_t maxOffset(uint32_t width, uint32_t height) const { |
| ssize_t offs = (allocatedDepth + 7) >> 3; |
| if (width > 0 && colInc > 0) { |
| offs += colInc * (ssize_t)(width - 1); |
| } |
| if (height > 0 && rowInc > 0) { |
| offs += rowInc * (ssize_t)(height - 1); |
| } |
| return offs; |
| } |
| } C2_PACK; |
| |
| struct C2PlanarLayout { |
| //public: |
| enum type_t : uint32_t { |
| TYPE_UNKNOWN = 0, |
| TYPE_YUV = 0x100, ///< YUV image with 3 planes |
| TYPE_YUVA, ///< YUVA image with 4 planes |
| TYPE_RGB, ///< RGB image with 3 planes |
| TYPE_RGBA, ///< RBGA image with 4 planes |
| }; |
| |
| type_t type; // image type |
| uint32_t numPlanes; // number of component planes |
| uint32_t rootPlanes; // number of layout planes (root planes) |
| |
| enum plane_index_t : uint32_t { |
| PLANE_Y = 0, |
| PLANE_U = 1, |
| PLANE_V = 2, |
| PLANE_R = 0, |
| PLANE_G = 1, |
| PLANE_B = 2, |
| PLANE_A = 3, |
| MAX_NUM_PLANES = 4, |
| }; |
| |
| C2PlaneInfo planes[MAX_NUM_PLANES]; |
| }; |
| |
| /** |
| * Aspect for objects that have a planar section (crop rectangle). |
| * |
| * This class is copiable. |
| */ |
| class _C2PlanarSectionAspect : public _C2PlanarCapacityAspect { |
| /// \name Planar section interface |
| /// @{ |
| private: |
| inline constexpr _C2PlanarSectionAspect(uint32_t width, uint32_t height, const C2Rect &crop) |
| : _C2PlanarCapacityAspect(width, height), |
| mCrop(C2Rect(std::min(width - std::min(crop.left, width), crop.width), |
| std::min(height - std::min(crop.top, height), crop.height)).at( |
| std::min(crop.left, width), |
| std::min(crop.height, height))) { |
| } |
| |
| public: |
| // crop can be an empty rect, does not have to line up with subsampling |
| // NOTE: we do not support floating-point crop |
| inline constexpr C2Rect crop() const { return mCrop; } |
| |
| /** |
| * Returns a child planar section for |crop|, where the capacity represents this section. |
| */ |
| inline constexpr _C2PlanarSectionAspect childSection(const C2Rect &crop) const { |
| return _C2PlanarSectionAspect( |
| mCrop.width, mCrop.height, |
| // crop and translate |crop| rect |
| C2Rect(c2_min(mCrop.right() - c2_clamp(mCrop.left, crop.left, mCrop.right()), |
| crop.width), |
| c2_min(mCrop.bottom() - c2_clamp(mCrop.top, crop.top, mCrop.bottom()), |
| crop.height)) |
| .at(c2_clamp(mCrop.left, crop.left, mCrop.right()) - mCrop.left, |
| c2_clamp(mCrop.top, crop.top, mCrop.bottom()) - mCrop.top)); |
| } |
| |
| protected: |
| inline constexpr _C2PlanarSectionAspect(const _C2PlanarCapacityAspect *parent) |
| : _C2PlanarCapacityAspect(parent), mCrop(width(), height()) {} |
| |
| inline constexpr _C2PlanarSectionAspect(const _C2PlanarCapacityAspect *parent, const C2Rect &crop) |
| : _C2PlanarCapacityAspect(parent), |
| mCrop(parent == nullptr ? C2Rect() : ((C2Rect)*parent).intersect(crop).normalize()) { } |
| |
| inline constexpr _C2PlanarSectionAspect(const _C2PlanarSectionAspect *parent, const C2Rect &crop) |
| : _C2PlanarCapacityAspect(parent), |
| mCrop(parent == nullptr ? C2Rect() : parent->crop().intersect(crop).normalize()) { } |
| |
| private: |
| friend class _C2EditablePlanarSectionAspect; |
| C2Rect mCrop; |
| /// @} |
| }; |
| |
| /** |
| * Aspect for objects that have an editable planar section (crop rectangle). |
| * |
| * This class is copiable. |
| */ |
| class _C2EditablePlanarSectionAspect : public _C2PlanarSectionAspect { |
| /// \name Planar section interface |
| /// @{ |
| using _C2PlanarSectionAspect::_C2PlanarSectionAspect; |
| |
| public: |
| // crop can be an empty rect, does not have to line up with subsampling |
| // NOTE: we do not support floating-point crop |
| inline constexpr C2Rect crop() const { return mCrop; } |
| |
| /** |
| * Sets crop to crop intersected with [(0,0) .. (width, height)] |
| */ |
| inline void setCrop_be(const C2Rect &crop) { |
| mCrop.left = std::min(width(), crop.left); |
| mCrop.top = std::min(height(), crop.top); |
| // It's guaranteed that mCrop.left <= width() && mCrop.top <= height() |
| mCrop.width = std::min(width() - mCrop.left, crop.width); |
| mCrop.height = std::min(height() - mCrop.top, crop.height); |
| } |
| |
| /** |
| * If crop is within the dimensions of this object, it sets crop to it. |
| * |
| * \return true iff crop is within the dimensions of this object |
| */ |
| inline bool setCrop(const C2Rect &crop) { |
| if (width() < crop.width || height() < crop.height |
| || width() - crop.width < crop.left || height() - crop.height < crop.top) { |
| return false; |
| } |
| mCrop = crop; |
| return true; |
| } |
| /// @} |
| }; |
| |
| /** |
| * Utility class for safe range calculations using size_t-s. |
| */ |
| class C2PlanarSection : public _C2PlanarSectionAspect { |
| public: |
| inline constexpr C2PlanarSection(const _C2PlanarCapacityAspect &parent, const C2Rect &crop) |
| : _C2PlanarSectionAspect(&parent, crop) { } |
| |
| inline constexpr C2PlanarSection(const _C2PlanarSectionAspect &parent, const C2Rect &crop) |
| : _C2PlanarSectionAspect(&parent, crop) { } |
| |
| inline constexpr C2PlanarSection intersect(const C2Rect &crop) const { |
| return C2PlanarSection(*this, crop); |
| } |
| }; |
| |
| /** |
| * Utility class for simple and safe planar capacity and section construction. |
| */ |
| class C2PlanarCapacity : public _C2PlanarCapacityAspect { |
| public: |
| inline constexpr explicit C2PlanarCapacity(size_t width, size_t height) |
| : _C2PlanarCapacityAspect(c2_min(width, std::numeric_limits<uint32_t>::max()), |
| c2_min(height, std::numeric_limits<uint32_t>::max())) { } |
| |
| inline constexpr C2PlanarSection section(const C2Rect &crop) const { |
| return C2PlanarSection(*this, crop); |
| } |
| }; |
| |
| |
| /** |
| * \ingroup graphic allocator |
| * 2D allocation interface. |
| */ |
| class C2GraphicAllocation : public _C2PlanarCapacityAspect { |
| public: |
| /** |
| * Maps a rectangular section (as defined by |rect|) of a 2D allocation into local process |
| * memory for flexible access. On success, it fills out |layout| with the plane specifications |
| * and fills the |addr| array with pointers to the first byte of the top-left pixel of each |
| * plane used. Otherwise, it leaves |layout| and |addr| untouched. |fence| will contain |
| * an acquire sync fence object. If it is already safe to access the |
| * buffer contents, then it will be an empty (already fired) fence. |
| * |
| * Safe regions for the pointer addresses returned can be gotten via C2LayoutInfo.minOffset()/ |
| * maxOffset(). |
| * |
| * \param rect section to be mapped (this does not have to be aligned) |
| * \param usage the desired usage. \todo this must be kSoftwareRead and/or |
| * kSoftwareWrite. |
| * \param fence a pointer to a fence object if an async mapping is requested. If |
| * not-null, and acquire fence will be stored here on success, or empty |
| * fence on failure. If null, the mapping will be synchronous. |
| * \param layout a pointer to where the mapped planes' descriptors will be |
| * stored. On failure, nullptr will be stored here. |
| * \param addr pointer to an array with at least C2PlanarLayout::MAX_NUM_PLANES |
| * elements. Only layout.numPlanes elements will be modified on success. |
| * |
| * \retval C2_OK the operation was successful |
| * \retval C2_REFUSED no permission to map the section |
| * \retval C2_DUPLICATE there is already a mapped region and this allocation cannot support |
| * multi-mapping (caller error) |
| * \retval C2_TIMED_OUT the operation timed out |
| * \retval C2_NO_MEMORY not enough memory to complete the operation |
| * \retval C2_BAD_VALUE the parameters (rect) are invalid or outside the allocation, or the |
| * usage flags are invalid (caller error) |
| * \retval C2_CORRUPTED some unknown error prevented the operation from completing (unexpected) |
| |
| */ |
| virtual c2_status_t map( |
| C2Rect rect, C2MemoryUsage usage, C2Fence *fence, |
| C2PlanarLayout *layout /* nonnull */, uint8_t **addr /* nonnull */) = 0; |
| |
| /** |
| * Unmaps a section of an allocation at |addr| with |rect|. These must be parameters previously |
| * passed to and returned by |map|; otherwise, this operation is a no-op. |
| * |
| * \param addr pointer to an array with at least C2PlanarLayout::MAX_NUM_PLANES |
| * elements containing the starting addresses of the mapped layers |
| * \param rect boundaries of the mapped section |
| * \param fence a pointer to a fence object if an async unmapping is requested. If |
| * not-null, a release fence will be stored here on success, or empty fence |
| * on failure. This fence signals when the original allocation contains |
| * all changes that happened to the mapped section. If null, the unmapping |
| * will be synchronous. |
| * |
| * \retval C2_OK the operation was successful |
| * \retval C2_TIMED_OUT the operation timed out |
| * \retval C2_NOT_FOUND there is no such mapped region (caller error) |
| * \retval C2_CORRUPTED some unknown error prevented the operation from completing (unexpected) |
| * \retval C2_REFUSED no permission to unmap the section (unexpected - system) |
| */ |
| virtual c2_status_t unmap( |
| uint8_t **addr /* nonnull */, C2Rect rect, C2Fence *fence /* nullable */) = 0; |
| |
| /** |
| * Returns the allocator ID for this allocation. This is useful to put the handle into context. |
| */ |
| virtual C2Allocator::id_t getAllocatorId() const = 0; |
| |
| /** |
| * Returns a pointer to the allocation handle. |
| */ |
| virtual const C2Handle *handle() const = 0; |
| |
| /** |
| * Returns true if this is the same allocation as |other|. |
| */ |
| virtual bool equals(const std::shared_ptr<const C2GraphicAllocation> &other) const = 0; |
| |
| protected: |
| using _C2PlanarCapacityAspect::_C2PlanarCapacityAspect; |
| virtual ~C2GraphicAllocation() = default; |
| }; |
| |
| class C2GraphicAllocation; |
| |
| /** |
| * A 2D block. |
| * |
| * \note width()/height() is not meaningful for users of blocks; instead, crop().width() and |
| * crop().height() is the capacity of the usable portion. Use and crop() if accessing the block |
| * directly through its handle to represent the allotted region of the underlying allocation to this |
| * block. |
| */ |
| class C2Block2D : public _C2PlanarSectionAspect { |
| public: |
| /** |
| * Returns the underlying handle for this allocation. |
| * |
| * \note that the block and its block pool has shared ownership of the handle |
| * and if all references to the block are released, the underlying block |
| * allocation may get reused even if a client keeps a clone of this handle. |
| */ |
| const C2Handle *handle() const; |
| |
| /** |
| * Returns the allocator's ID that created the underlying allocation for this block. This |
| * provides the context for understanding the handle. |
| */ |
| C2Allocator::id_t getAllocatorId() const; |
| |
| protected: |
| class Impl; |
| C2Block2D(std::shared_ptr<Impl> impl, const _C2PlanarSectionAspect §ion); |
| |
| friend struct _C2BlockFactory; |
| std::shared_ptr<Impl> mImpl; |
| }; |
| |
| /** |
| * Graphic view provides read or read-write access for a graphic block. |
| * |
| * This class is copiable. |
| * |
| * \note Due to the subsampling of graphic buffers, a read view must still contain a crop rectangle |
| * to ensure subsampling is followed. This results in nearly identical interface between read and |
| * write views, so C2GraphicView can encompass both of them. |
| */ |
| class C2GraphicView : public _C2EditablePlanarSectionAspect { |
| public: |
| /** |
| * \return array of pointers (of layout().numPlanes elements) to the start of the planes or |
| * nullptr on error. Regardless of crop rect, they always point to the top-left corner of each |
| * plane. Access outside of the crop rect results in an undefined behavior. |
| */ |
| const uint8_t *const *data() const; |
| |
| /** |
| * \return array of pointers (of layout().numPlanes elements) to the start of the planes or |
| * nullptr on error. Regardless of crop rect, they always point to the top-left corner of each |
| * plane. Access outside of the crop rect results in an undefined behavior. |
| */ |
| uint8_t *const *data(); |
| |
| /** |
| * \return layout of the graphic block to interpret the returned data. |
| */ |
| const C2PlanarLayout layout() const; |
| |
| /** |
| * Returns a section of this view. |
| * |
| * \param rect the dimension of the section. \note This is clamped to the crop of this view. |
| * |
| * \return a read view containing the requested section of this view |
| */ |
| const C2GraphicView subView(const C2Rect &rect) const; |
| C2GraphicView subView(const C2Rect &rect); |
| |
| /** |
| * \return error during the creation/mapping of this view. |
| */ |
| c2_status_t error() const; |
| |
| protected: |
| class Impl; |
| C2GraphicView(std::shared_ptr<Impl> impl, const _C2PlanarSectionAspect §ion); |
| explicit C2GraphicView(c2_status_t error); |
| |
| private: |
| friend struct _C2BlockFactory; |
| std::shared_ptr<Impl> mImpl; |
| }; |
| |
| /** |
| * A constant (read-only) graphic block (portion of an allocation) with an acquire fence. |
| * Blocks are unmapped when created, and can be mapped into a read view on demand. |
| * |
| * This class is copiable and contains a reference to the allocation that it is based on. |
| */ |
| class C2ConstGraphicBlock : public C2Block2D { |
| public: |
| /** |
| * Maps this block into memory and returns a read view for it. |
| * |
| * \return a read view for this block. |
| */ |
| C2Acquirable<const C2GraphicView> map() const; |
| |
| /** |
| * Returns a section of this block. |
| * |
| * \param rect the coordinates of the section. \note This is clamped to the crop rectangle of |
| * this block. |
| * |
| * \return a constant graphic block containing a portion of this block |
| */ |
| C2ConstGraphicBlock subBlock(const C2Rect &rect) const; |
| |
| /** |
| * Returns the acquire fence for this block. |
| * |
| * \return a fence that must be waited on before reading the block. |
| */ |
| C2Fence fence() const { return mFence; } |
| |
| protected: |
| C2ConstGraphicBlock( |
| std::shared_ptr<Impl> impl, const _C2PlanarSectionAspect §ion, C2Fence fence); |
| |
| private: |
| friend struct _C2BlockFactory; |
| C2Fence mFence; |
| }; |
| |
| /** |
| * Graphic block is a writeable 2D block. Once written, it can be shared in whole or in part with |
| * consumers/readers as read-only const graphic block. |
| */ |
| class C2GraphicBlock : public C2Block2D { |
| public: |
| /** |
| * Maps this block into memory and returns a write view for it. |
| * |
| * \return a write view for this block. |
| */ |
| C2Acquirable<C2GraphicView> map(); |
| |
| /** |
| * Creates a read-only const linear block for a portion of this block; optionally protected |
| * by an acquire fence. There are two ways to use this: |
| * |
| * 1) share ready block after writing data into the block. In this case no fence shall be |
| * supplied, and the block shall not be modified after calling this method. |
| * 2) share block metadata before actually (finishing) writing the data into the block. In |
| * this case a fence must be supplied that will be triggered when the data is written. |
| * The block shall be modified only until firing the event for the fence. |
| */ |
| C2ConstGraphicBlock share(const C2Rect &crop, C2Fence fence); |
| |
| protected: |
| C2GraphicBlock(std::shared_ptr<Impl> impl, const _C2PlanarSectionAspect §ion); |
| |
| friend struct _C2BlockFactory; |
| }; |
| |
| /// @} |
| |
| /// \defgroup buffer_onj Buffer objects |
| /// @{ |
| |
| // ================================================================================================ |
| // BUFFERS |
| // ================================================================================================ |
| |
| /// \todo: Do we still need this? |
| /// |
| // There are 2 kinds of buffers: linear or graphic. Linear buffers can contain a single block, or |
| // a list of blocks (LINEAR_CHUNKS). Support for list of blocks is optional, and can allow consuming |
| // data from circular buffers or scattered data sources without extra memcpy. Currently, list of |
| // graphic blocks is not supported. |
| |
| class C2LinearBuffer; // read-write buffer |
| class C2GraphicBuffer; // read-write buffer |
| class C2LinearChunksBuffer; |
| |
| /** |
| * C2BufferData: the main, non-meta data of a buffer. A buffer can contain either linear blocks |
| * or graphic blocks, and can contain either a single block or multiple blocks. This is determined |
| * by its type. |
| */ |
| class C2BufferData { |
| public: |
| /** |
| * The type of buffer data. |
| */ |
| enum type_t : uint32_t { |
| INVALID, ///< invalid buffer type. Do not use. |
| LINEAR, ///< the buffer contains a single linear block |
| LINEAR_CHUNKS, ///< the buffer contains one or more linear blocks |
| GRAPHIC, ///< the buffer contains a single graphic block |
| GRAPHIC_CHUNKS, ///< the buffer contains one of more graphic blocks |
| }; |
| |
| /** |
| * Gets the type of this buffer (data). |
| * \return the type of this buffer data. |
| */ |
| type_t type() const; |
| |
| /** |
| * Gets the linear blocks of this buffer. |
| * \return a constant list of const linear blocks of this buffer. |
| * \retval empty list if this buffer does not contain linear block(s). |
| */ |
| const std::vector<C2ConstLinearBlock> linearBlocks() const; |
| |
| /** |
| * Gets the graphic blocks of this buffer. |
| * \return a constant list of const graphic blocks of this buffer. |
| * \retval empty list if this buffer does not contain graphic block(s). |
| */ |
| const std::vector<C2ConstGraphicBlock> graphicBlocks() const; |
| |
| private: |
| class Impl; |
| std::shared_ptr<Impl> mImpl; |
| |
| protected: |
| // no public constructor |
| explicit C2BufferData(const std::vector<C2ConstLinearBlock> &blocks); |
| explicit C2BufferData(const std::vector<C2ConstGraphicBlock> &blocks); |
| }; |
| |
| /** |
| * C2Buffer: buffer base class. These are always used as shared_ptrs. Though the underlying buffer |
| * objects (native buffers, ion buffers, or dmabufs) are reference-counted by the system, |
| * C2Buffers hold only a single reference. |
| * |
| * These objects cannot be used on the stack. |
| */ |
| class C2Buffer { |
| public: |
| /** |
| * Gets the buffer's data. |
| * |
| * \return the buffer's data. |
| */ |
| const C2BufferData data() const; |
| |
| ///@name Pre-destroy notification handling |
| ///@{ |
| |
| /** |
| * Register for notification just prior to the destruction of this object. |
| */ |
| typedef void (*OnDestroyNotify) (const C2Buffer *buf, void *arg); |
| |
| /** |
| * Registers for a pre-destroy notification. This is called just prior to the destruction of |
| * this buffer (when this buffer is no longer valid.) |
| * |
| * \param onDestroyNotify the notification callback |
| * \param arg an arbitrary parameter passed to the callback |
| * |
| * \retval C2_OK the registration was successful. |
| * \retval C2_DUPLICATE a notification was already registered for this callback and argument |
| * \retval C2_NO_MEMORY not enough memory to register for this callback |
| * \retval C2_CORRUPTED an unknown error prevented the registration (unexpected) |
| */ |
| c2_status_t registerOnDestroyNotify(OnDestroyNotify onDestroyNotify, void *arg = nullptr); |
| |
| /** |
| * Unregisters a previously registered pre-destroy notification. |
| * |
| * \param onDestroyNotify the notification callback |
| * \param arg an arbitrary parameter passed to the callback |
| * |
| * \retval C2_OK the unregistration was successful. |
| * \retval C2_NOT_FOUND the notification was not found |
| * \retval C2_CORRUPTED an unknown error prevented the registration (unexpected) |
| */ |
| c2_status_t unregisterOnDestroyNotify(OnDestroyNotify onDestroyNotify, void *arg = nullptr); |
| |
| ///@} |
| |
| virtual ~C2Buffer() = default; |
| |
| ///@name Buffer-specific arbitrary metadata handling |
| ///@{ |
| |
| /** |
| * Gets the list of metadata associated with this buffer. |
| * |
| * \return a constant list of info objects associated with this buffer. |
| */ |
| const std::vector<std::shared_ptr<const C2Info>> info() const; |
| |
| /** |
| * Attaches (or updates) an (existing) metadata for this buffer. |
| * If the metadata is stream specific, the stream information will be reset. |
| * |
| * \param info Metadata to update |
| * |
| * \retval C2_OK the metadata was successfully attached/updated. |
| * \retval C2_NO_MEMORY not enough memory to attach the metadata (this return value is not |
| * used if the same kind of metadata is already attached to the buffer). |
| */ |
| c2_status_t setInfo(const std::shared_ptr<C2Info> &info); |
| |
| /** |
| * Checks if there is a certain type of metadata attached to this buffer. |
| * |
| * \param index the parameter type of the metadata |
| * |
| * \return true iff there is a metadata with the parameter type attached to this buffer. |
| */ |
| bool hasInfo(C2Param::Type index) const; |
| |
| /** |
| * Checks if there is a certain type of metadata attached to this buffer, and returns a |
| * shared pointer to it if there is. Returns an empty shared pointer object (nullptr) if there |
| * is not. |
| * |
| * \param index the parameter type of the metadata |
| * |
| * \return shared pointer to the metadata. |
| */ |
| std::shared_ptr<const C2Info> getInfo(C2Param::Type index) const; |
| |
| /** |
| * Removes a metadata from the buffer. |
| */ |
| std::shared_ptr<C2Info> removeInfo(C2Param::Type index); |
| ///@} |
| |
| /** |
| * Creates a buffer containing a single linear block. |
| * |
| * \param block the content of the buffer. |
| * |
| * \return shared pointer to the created buffer. |
| */ |
| static std::shared_ptr<C2Buffer> CreateLinearBuffer(const C2ConstLinearBlock &block); |
| |
| /** |
| * Creates a buffer containing a single graphic block. |
| * |
| * \param block the content of the buffer. |
| * |
| * \return shared pointer to the created buffer. |
| */ |
| static std::shared_ptr<C2Buffer> CreateGraphicBuffer(const C2ConstGraphicBlock &block); |
| |
| protected: |
| // no public constructor |
| explicit C2Buffer(const std::vector<C2ConstLinearBlock> &blocks); |
| explicit C2Buffer(const std::vector<C2ConstGraphicBlock> &blocks); |
| |
| private: |
| class Impl; |
| std::shared_ptr<Impl> mImpl; |
| }; |
| |
| /** |
| * An extension of C2Info objects that can contain arbitrary buffer data. |
| * |
| * \note This object is not describable and contains opaque data. |
| */ |
| class C2InfoBuffer { |
| public: |
| /** |
| * Gets the index of this info object. |
| * |
| * \return the parameter index. |
| */ |
| const C2Param::Index index() const; |
| |
| /** |
| * Gets the buffer's data. |
| * |
| * \return the buffer's data. |
| */ |
| const C2BufferData data() const; |
| }; |
| |
| /// @} |
| |
| /// @} |
| |
| #endif // C2BUFFER_H_ |
