Move Codec2-related code from hardware/google/av
Test: None
Bug: 112362730
Change-Id: Ie2f8ff431d65c40333f267ab9877d47089adeea4
diff --git a/media/codec2/include/C2Buffer.h b/media/codec2/include/C2Buffer.h
new file mode 100644
index 0000000..2997f6e
--- /dev/null
+++ b/media/codec2/include/C2Buffer.h
@@ -0,0 +1,2305 @@
+/*
+ * 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_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_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_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
+ };
+ typedef type_t Type; // deprecated
+
+ /**
+ * 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;
+
+ /**
+ * These will still work if used in onDeathNotify.
+ */
+#if 0
+ inline std::shared_ptr<C2LinearBuffer> asLinearBuffer() const {
+ return mType == LINEAR ? std::shared_ptr::reinterpret_cast<C2LinearBuffer>(this) : nullptr;
+ }
+
+ inline std::shared_ptr<C2GraphicBuffer> asGraphicBuffer() const {
+ return mType == GRAPHIC ? std::shared_ptr::reinterpret_cast<C2GraphicBuffer>(this) : nullptr;
+ }
+
+ inline std::shared_ptr<C2CircularBuffer> asCircularBuffer() const {
+ return mType == CIRCULAR ? std::shared_ptr::reinterpret_cast<C2CircularBuffer>(this) : nullptr;
+ }
+#endif
+
+ ///@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;
+// Type _mType;
+};
+
+/**
+ * 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;
+};
+
+/// @}
+
+/// \cond INTERNAL
+
+/// \todo These are no longer used
+
+/// \addtogroup linear
+/// @{
+
+/** \deprecated */
+class C2LinearBuffer
+ : public C2Buffer, public _C2LinearRangeAspect,
+ public std::enable_shared_from_this<C2LinearBuffer> {
+public:
+ /** \todo what is this? */
+ const C2Handle *handle() const;
+
+protected:
+ inline C2LinearBuffer(const C2ConstLinearBlock &block);
+
+private:
+ class Impl;
+ Impl *mImpl;
+};
+
+class C2ReadCursor;
+
+class C2WriteCursor {
+public:
+ uint32_t remaining() const; // remaining data to be read
+ void commit(); // commits the current position. discard data before current position
+ void reset() const; // resets position to the last committed position
+ // slices off at most |size| bytes, and moves cursor ahead by the number of bytes
+ // sliced off.
+ C2ReadCursor slice(uint32_t size) const;
+ // slices off at most |size| bytes, and moves cursor ahead by the number of bytes
+ // sliced off.
+ C2WriteCursor reserve(uint32_t size);
+ // bool read(T&);
+ // bool write(T&);
+ C2Fence waitForSpace(uint32_t size);
+};
+
+/// @}
+
+/// \addtogroup graphic
+/// @{
+
+struct C2ColorSpace {
+//public:
+ enum Standard {
+ BT601,
+ BT709,
+ BT2020,
+ // TODO
+ };
+
+ enum Range {
+ LIMITED,
+ FULL,
+ // TODO
+ };
+
+ enum TransferFunction {
+ BT709Transfer,
+ BT2020Transfer,
+ HybridLogGamma2,
+ HybridLogGamma4,
+ // TODO
+ };
+};
+
+/** \deprecated */
+class C2GraphicBuffer : public C2Buffer {
+public:
+ // constant attributes
+ inline uint32_t width() const { return mWidth; }
+ inline uint32_t height() const { return mHeight; }
+ inline uint32_t format() const { return mFormat; }
+ inline const C2MemoryUsage usage() const { return mUsage; }
+
+ // modifiable attributes
+
+
+ virtual const C2ColorSpace colorSpace() const = 0;
+ // best effort
+ virtual void setColorSpace_be(const C2ColorSpace &colorSpace) = 0;
+ virtual bool setColorSpace(const C2ColorSpace &colorSpace) = 0;
+
+ const C2Handle *handle() const;
+
+protected:
+ uint32_t mWidth;
+ uint32_t mHeight;
+ uint32_t mFormat;
+ C2MemoryUsage mUsage;
+
+ class Impl;
+ Impl *mImpl;
+};
+
+/// @}
+
+/// \endcond
+
+/// @}
+
+#endif // C2BUFFER_H_