| /* |
| * 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 <C2Param.h> // for C2Info |
| |
| #include <list> |
| #include <memory> |
| |
| typedef int C2Fence; |
| |
| #ifdef __ANDROID__ |
| |
| // #include <system/window.h> |
| #include <cutils/native_handle.h> |
| #include <hardware/gralloc.h> // TODO: remove |
| |
| typedef native_handle_t C2Handle; |
| |
| #else |
| |
| typedef void* C2Handle; |
| |
| #endif |
| |
| namespace android { |
| |
| /// \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_NO_PERMISSION no permission to wait for the fence (unexpected - system) |
| * \retval C2_CORRUPTED some unknown error prevented waiting for the fence (unexpected) |
| */ |
| C2Error wait(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; |
| |
| private: |
| class Impl; |
| std::shared_ptr<Impl> mImpl; |
| }; |
| |
| /** |
| * 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_ALREADY_EXISTS the fence(s) have already been signaled (caller error) |
| * \retval C2_NO_PERMISSION no permission to signal the fence (unexpected - system) |
| * \retval C2_CORRUPTED some unknown error prevented signaling the fence(s) (unexpected) |
| */ |
| C2Error 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_ALREADY_EXISTS the fence have already been merged (caller error) |
| * \retval C2_BAD_STATE the fence have already been signaled or abandoned (caller error) |
| * \retval C2_NO_PERMISSION no permission to merge the fence (unexpected - system) |
| * \retval C2_CORRUPTED some unknown error prevented merging the fence(s) (unexpected) |
| */ |
| C2Error 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_ALREADY_EXISTS the fence(s) have already been abandoned (caller error) |
| * \retval C2_NO_PERMISSION no permission to abandon the fence (unexpected - system) |
| * \retval C2_CORRUPTED some unknown error prevented signaling the fence(s) (unexpected) |
| */ |
| C2Error abandon(); |
| |
| private: |
| class Impl; |
| std::shared_ptr<Impl> mImpl; |
| }; |
| |
| /// \addtogroup buf_internal Internal |
| /// @{ |
| |
| /** |
| * Interface for objects that encapsulate an updatable error value. |
| */ |
| struct _C2InnateError { |
| inline C2Error error() const { return mError; } |
| |
| protected: |
| _C2InnateError(C2Error error) : mError(error) { } |
| |
| C2Error mError; // this error 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(); |
| |
| protected: |
| C2Acquirable(C2Error error, C2Fence fence, T t) : C2Fence(fence), mInitialError(error), mT(t) { } |
| |
| private: |
| C2Error mInitialError; |
| T mT; // TODO: move instead of copy |
| }; |
| |
| /// @} |
| |
| /// \defgroup linear Linear Data Blocks |
| /// @{ |
| |
| /************************************************************************************************** |
| LINEAR ASPECTS, BLOCKS AND VIEWS |
| **************************************************************************************************/ |
| |
| /** |
| * Common aspect for all objects that have a linear capacity. |
| */ |
| class _C2LinearCapacityAspect { |
| /// \name Linear capacity interface |
| /// @{ |
| public: |
| inline uint32_t capacity() const { return 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 _C2LinearCapacityAspect(uint32_t capacity) |
| : mCapacity(capacity) { } |
| |
| inline explicit _C2LinearCapacityAspect(const _C2LinearCapacityAspect *parent) |
| : mCapacity(parent == nullptr ? 0 : parent->capacity()) { } |
| |
| private: |
| const uint32_t mCapacity; |
| /// @} |
| }; |
| |
| /** |
| * Aspect for objects that have a linear range. |
| * |
| * This class is copiable. |
| */ |
| class _C2LinearRangeAspect : public _C2LinearCapacityAspect { |
| /// \name Linear range interface |
| /// @{ |
| public: |
| inline uint32_t offset() const { return mOffset; } |
| inline uint32_t size() const { return mSize; } |
| |
| protected: |
| inline explicit _C2LinearRangeAspect(const _C2LinearCapacityAspect *parent) |
| : _C2LinearCapacityAspect(parent), |
| mOffset(0), |
| mSize(capacity()) { } |
| |
| inline _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 two [offset, offset + size] ranges |
| inline _C2LinearRangeAspect(const _C2LinearRangeAspect *parent, size_t offset, size_t size) |
| : _C2LinearCapacityAspect(parent == nullptr ? 0 : parent->capacity()), |
| mOffset(c2_min(c2_max(offset, parent == nullptr ? 0 : parent->offset()), capacity())), |
| mSize(c2_min(c2_min(size, parent == nullptr ? 0 : parent->size()), capacity() - mOffset)) { } |
| |
| private: |
| friend class _C2EditableLinearRange; |
| // invariants 0 <= mOffset <= mOffset + mSize <= capacity() |
| uint32_t mOffset; |
| uint32_t mSize; |
| /// @} |
| }; |
| |
| /** |
| * Aspect for objects that have an editable linear range. |
| * |
| * This class is copiable. |
| */ |
| class _C2EditableLinearRange : public _C2LinearRangeAspect { |
| protected: |
| inline explicit _C2EditableLinearRange(const _C2LinearCapacityAspect *parent) |
| : _C2LinearRangeAspect(parent) { } |
| |
| inline _C2EditableLinearRange(const _C2LinearCapacityAspect *parent, size_t offset, size_t size) |
| : _C2LinearRangeAspect(parent, offset, size) { } |
| |
| // subsection of the two [offset, offset + size] ranges |
| inline _C2EditableLinearRange(const _C2LinearRangeAspect *parent, size_t offset, size_t size) |
| : _C2LinearRangeAspect(parent, offset, size) { } |
| |
| /// \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) { |
| if (offset > capacity()) { |
| offset = capacity(); |
| } |
| if (offset > mOffset + mSize) { |
| mSize = 0; |
| } else { |
| mSize = mOffset + mSize - offset; |
| } |
| mOffset = offset; |
| } |
| /** |
| * 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 = std::min(size, capacity() - mOffset); |
| } |
| /// @} |
| }; |
| |
| // ================================================================================================ |
| // BLOCKS |
| // ================================================================================================ |
| |
| /** |
| * Blocks are sections of allocations. They can be either 1D or 2D. |
| */ |
| |
| class C2LinearAllocation; |
| |
| class C2Block1D : public _C2LinearRangeAspect { |
| public: |
| const C2Handle *handle() const; |
| |
| protected: |
| C2Block1D(std::shared_ptr<C2LinearAllocation> alloc); |
| C2Block1D(std::shared_ptr<C2LinearAllocation> alloc, size_t offset, size_t size); |
| |
| private: |
| class Impl; |
| 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. |
| */ |
| const uint8_t *data(); |
| |
| /** |
| * 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. |
| */ |
| C2Error error(); |
| |
| private: |
| class Impl; |
| std::shared_ptr<Impl> mImpl; |
| }; |
| |
| /** |
| * Write view provides read/write access for a linear memory segment. |
| * |
| * This class is copiable. \todo movable only? |
| */ |
| class C2WriteView : public _C2EditableLinearRange { |
| public: |
| /** |
| * Start of the block. |
| * |
| * \return pointer to the start of the block or nullptr on error. |
| */ |
| uint8_t *base(); |
| |
| /** |
| * \return pointer to the block at the current offset or nullptr on error. |
| */ |
| uint8_t *data(); |
| |
| /** |
| * \return error during the creation/mapping of this view. |
| */ |
| C2Error error(); |
| |
| private: |
| class Impl; |
| /// \todo should this be unique_ptr to make this movable only - to avoid inconsistent regions |
| /// between copies. |
| 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; } |
| |
| private: |
| 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); |
| }; |
| |
| /// @} |
| |
| /************************************************************************************************** |
| 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) |
| */ |
| C2Error 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) |
| */ |
| C2Error 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 list 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) |
| */ |
| C2Error share(size_t size, C2Fence fence, std::list<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. |
| */ |
| C2Error error(); |
| }; |
| |
| /** |
| * 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) |
| */ |
| C2Error 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 |
| /// @{ |
| |
| /** |
| * Interface for objects that have a width and height (planar capacity). |
| */ |
| class _C2PlanarCapacityAspect { |
| /// \name Planar capacity interface |
| /// @{ |
| public: |
| inline uint32_t width() const { return mWidth; } |
| inline uint32_t height() const { return mHeight; } |
| |
| protected: |
| inline _C2PlanarCapacityAspect(uint32_t width, uint32_t height) |
| : mWidth(width), mHeight(height) { } |
| |
| inline _C2PlanarCapacityAspect(const _C2PlanarCapacityAspect *parent) |
| : mWidth(parent == nullptr ? 0 : parent->width()), |
| mHeight(parent == nullptr ? 0 : parent->height()) { } |
| |
| private: |
| const uint32_t mWidth; |
| const uint32_t mHeight; |
| /// @} |
| }; |
| |
| /** |
| * 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 mLeft; |
| uint32_t mTop; |
| uint32_t mWidth; |
| uint32_t mHeight; |
| |
| inline C2Rect(uint32_t width, uint32_t height) |
| : C2Rect(width, height, 0, 0) { } |
| |
| inline C2Rect(uint32_t width, uint32_t height, uint32_t left, uint32_t top) |
| : mLeft(left), mTop(top), mWidth(width), mHeight(height) { } |
| |
| // utility methods |
| |
| inline bool isEmpty() const { |
| return mWidth == 0 || mHeight == 0; |
| } |
| |
| inline bool isValid() const { |
| return mLeft <= ~mWidth && mTop <= ~mHeight; |
| } |
| |
| inline operator bool() const { |
| return isValid() && !isEmpty(); |
| } |
| |
| inline bool operator!() const { |
| return !bool(*this); |
| } |
| |
| inline bool contains(const C2Rect &other) const { |
| if (!isValid() || !other.isValid()) { |
| return false; |
| } else if (other.isEmpty()) { |
| return true; |
| } else { |
| return mLeft <= other.mLeft && mTop <= other.mTop |
| && mLeft + mWidth >= other.mLeft + other.mWidth |
| && mTop + mHeight >= other.mTop + other.mHeight; |
| } |
| } |
| |
| inline bool operator==(const C2Rect &other) const { |
| if (!isValid()) { |
| return !other.isValid(); |
| } else if (isEmpty()) { |
| return other.isEmpty(); |
| } else { |
| return mLeft == other.mLeft && mTop == other.mTop |
| && mWidth == other.mWidth && mHeight == other.mHeight; |
| } |
| } |
| |
| inline bool operator!=(const C2Rect &other) const { |
| return !operator==(other); |
| } |
| |
| inline bool operator>=(const C2Rect &other) const { |
| return contains(other); |
| } |
| |
| inline bool operator>(const C2Rect &other) const { |
| return contains(other) && !operator==(other); |
| } |
| |
| inline bool operator<=(const C2Rect &other) const { |
| return other.contains(*this); |
| } |
| |
| inline bool operator<(const C2Rect &other) const { |
| return other.contains(*this) && !operator==(other); |
| } |
| }; |
| |
| /** |
| * C2PlaneInfo: information on the layout of flexible planes. |
| * |
| * Public fields without getters/setters. |
| */ |
| struct C2PlaneInfo { |
| // public: |
| enum Channel : uint32_t { |
| Y, |
| R, |
| G, |
| B, |
| A, |
| Cr, |
| Cb, |
| } mChannel; |
| |
| int32_t mColInc; // column increment in bytes. may be negative |
| int32_t mRowInc; // row increment in bytes. may be negative |
| uint32_t mHorizSubsampling; // subsampling compared to width |
| uint32_t mVertSubsampling; // subsampling compared to height |
| |
| uint32_t mBitDepth; |
| uint32_t mAllocatedDepth; |
| |
| inline ssize_t minOffset(uint32_t width, uint32_t height) { |
| ssize_t offs = 0; |
| if (width > 0 && mColInc < 0) { |
| offs += mColInc * (ssize_t)(width - 1); |
| } |
| if (height > 0 && mRowInc < 0) { |
| offs += mRowInc * (ssize_t)(height - 1); |
| } |
| return offs; |
| } |
| |
| inline ssize_t maxOffset(uint32_t width, uint32_t height, uint32_t allocatedDepth) { |
| ssize_t offs = (allocatedDepth + 7) >> 3; |
| if (width > 0 && mColInc > 0) { |
| offs += mColInc * (ssize_t)(width - 1); |
| } |
| if (height > 0 && mRowInc > 0) { |
| offs += mRowInc * (ssize_t)(height - 1); |
| } |
| return offs; |
| } |
| }; |
| |
| struct C2PlaneLayout { |
| public: |
| enum Type : uint32_t { |
| MEDIA_IMAGE_TYPE_UNKNOWN = 0, |
| MEDIA_IMAGE_TYPE_YUV = 0x100, |
| MEDIA_IMAGE_TYPE_YUVA, |
| MEDIA_IMAGE_TYPE_RGB, |
| MEDIA_IMAGE_TYPE_RGBA, |
| }; |
| |
| Type mType; |
| uint32_t mNumPlanes; // number of planes |
| |
| enum PlaneIndex : uint32_t { |
| Y = 0, |
| U = 1, |
| V = 2, |
| R = 0, |
| G = 1, |
| B = 2, |
| A = 3, |
| MAX_NUM_PLANES = 4, |
| }; |
| |
| C2PlaneInfo mPlanes[MAX_NUM_PLANES]; |
| }; |
| |
| /** |
| * Aspect for objects that have a planar section (crop rectangle). |
| * |
| * This class is copiable. |
| */ |
| class _C2PlanarSection : public _C2PlanarCapacityAspect { |
| /// \name Planar section interface |
| /// @{ |
| public: |
| // crop can be an empty rect, does not have to line up with subsampling |
| // NOTE: we do not support floating-point crop |
| inline const C2Rect crop() { return mCrop; } |
| |
| /** |
| * Sets crop to crop intersected with [(0,0) .. (width, height)] |
| */ |
| inline void setCrop_be(const C2Rect &crop); |
| |
| /** |
| * 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); |
| |
| private: |
| C2Rect mCrop; |
| /// @} |
| }; |
| |
| class C2Block2D : public _C2PlanarSection { |
| public: |
| const C2Handle *handle() const; |
| |
| private: |
| class Impl; |
| 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 _C2PlanarSection { |
| public: |
| /** |
| * \return pointer to the start of the block or nullptr on error. |
| */ |
| const uint8_t *data() const; |
| |
| /** |
| * \return pointer to the start of the block or nullptr on error. |
| */ |
| uint8_t *data(); |
| |
| /** |
| * 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. |
| */ |
| C2Error error() const; |
| |
| private: |
| class Impl; |
| 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; } |
| |
| private: |
| 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); |
| }; |
| |
| /// @} |
| |
| /// \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 : uint32_t { |
| 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 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::list<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::list<C2ConstGraphicBlock> graphicBlocks() const; |
| |
| private: |
| class Impl; |
| std::shared_ptr<Impl> mImpl; |
| |
| protected: |
| // no public constructor |
| // C2BufferData(const std::shared_ptr<const Impl> &impl) : mImpl(impl) {} |
| }; |
| |
| /** |
| * 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) |
| */ |
| C2Error 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) |
| */ |
| C2Error 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::list<std::shared_ptr<const C2Info>> infos() 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). |
| */ |
| C2Error 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; |
| std::shared_ptr<C2Info> removeInfo(C2Param::Type index) const; |
| ///@} |
| |
| protected: |
| // no public constructor |
| inline C2Buffer() = default; |
| |
| private: |
| // 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; |
| }; |
| |
| /// @} |
| |
| /************************************************************************************************** |
| ALLOCATIONS |
| **************************************************************************************************/ |
| |
| /// \defgroup allocator Allocation and memory placement |
| /// @{ |
| |
| /** |
| * Buffer/memory usage bits. These are used by the allocators to select optimal memory type/pool and |
| * buffer layout. |
| * |
| * \note This struct has public fields without getters/setters. All methods are inline. |
| */ |
| struct C2MemoryUsage { |
| // public: |
| // TODO: match these to gralloc1.h |
| enum Consumer : uint64_t { |
| kSoftwareRead = GRALLOC_USAGE_SW_READ_OFTEN, |
| kRenderScriptRead = GRALLOC_USAGE_RENDERSCRIPT, |
| kTextureRead = GRALLOC_USAGE_HW_TEXTURE, |
| kHardwareComposer = GRALLOC_USAGE_HW_COMPOSER, |
| kHardwareEncoder = GRALLOC_USAGE_HW_VIDEO_ENCODER, |
| kProtectedRead = GRALLOC_USAGE_PROTECTED, |
| }; |
| |
| enum Producer : uint64_t { |
| kSoftwareWrite = GRALLOC_USAGE_SW_WRITE_OFTEN, |
| kRenderScriptWrite = GRALLOC_USAGE_RENDERSCRIPT, |
| kTextureWrite = GRALLOC_USAGE_HW_RENDER, |
| kCompositionTarget = GRALLOC_USAGE_HW_COMPOSER | GRALLOC_USAGE_HW_RENDER, |
| kHardwareDecoder = GRALLOC_USAGE_HW_VIDEO_ENCODER, |
| kProtectedWrite = GRALLOC_USAGE_PROTECTED, |
| }; |
| |
| uint64_t mConsumer; // e.g. input |
| uint64_t mProducer; // e.g. output |
| }; |
| |
| /** |
| * \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. |
| * |fenceFd| is a file descriptor referring to an acquire sync fence object. If it is already |
| * safe to access the buffer contents, then -1. |
| * |
| * \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 fenceFd a pointer to a file descriptor if an async mapping is requested. If |
| * not-null, and acquire fence FD will be stored here on success, or -1 |
| * 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_NO_PERMISSION no permission to map the portion |
| * \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 (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 C2Error map( |
| size_t offset, size_t size, C2MemoryUsage usage, int *fenceFd /* nullable */, |
| void **addr /* nonnull */) = 0; |
| |
| /** |
| * Unmaps a portion of an allocation at |addr| with |size|. These must be parameters previously |
| * passed to |map|; otherwise, this operation is a no-op. |
| * |
| * \param addr starting address of the mapped region |
| * \param size size of the mapped region |
| * \param fenceFd a pointer to a file descriptor if an async unmapping is requested. If |
| * not-null, a release fence FD will be stored here on success, or -1 |
| * on failure. This fence signals when the original allocation contains |
| * any 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_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_NO_PERMISSION no permission to unmap the portion (unexpected - system) |
| */ |
| virtual C2Error unmap(void *addr, size_t size, int *fenceFd /* nullable */) = 0; |
| |
| /** |
| * Returns true if this is a valid allocation. |
| * |
| * \todo remove? |
| */ |
| virtual bool isValid() 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; |
| }; |
| |
| /** |
| * \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. |fenceFd| is a file |
| * descriptor referring to an acquire sync fence object. If it is already safe to access the |
| * buffer contents, then -1. |
| * |
| * \note Only one portion of the graphic allocation can be mapped at the same time. (This is |
| * from gralloc1 limitation.) |
| * |
| * \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 fenceFd a pointer to a file descriptor if an async mapping is requested. If |
| * not-null, and acquire fence FD will be stored here on success, or -1 |
| * 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. |
| * |
| * \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_NO_PERMISSION no permission to map the section |
| * \retval C2_ALREADY_EXISTS there is already a mapped region (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 C2Error map( |
| C2Rect rect, C2MemoryUsage usage, int *fenceFd, |
| // TODO: return <addr, size> buffers with plane sizes |
| C2PlaneLayout *layout /* nonnull */, uint8_t **addr /* nonnull */) = 0; |
| |
| /** |
| * Unmaps the last mapped rectangular section. |
| * |
| * \param fenceFd a pointer to a file descriptor if an async unmapping is requested. If |
| * not-null, a release fence FD will be stored here on success, or -1 |
| * on failure. This fence signals when the original allocation contains |
| * any 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 mapped region (caller error) |
| * \retval C2_CORRUPTED some unknown error prevented the operation from completing (unexpected) |
| * \retval C2_NO_PERMISSION no permission to unmap the section (unexpected - system) |
| */ |
| virtual C2Error unmap(C2Fence *fenceFd /* nullable */) = 0; |
| |
| /** |
| * Returns true if this is a valid allocation. |
| * |
| * \todo remove? |
| */ |
| virtual bool isValid() 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) = 0; |
| |
| protected: |
| virtual ~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: |
| /** |
| * 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_NO_PERMISSION no permission to complete the allocation |
| * \retval C2_BAD_VALUE capacity or usage are not supported (invalid) (caller error) |
| * \retval C2_UNSUPPORTED this allocator does not support 1D allocations |
| * \retval C2_CORRUPTED some unknown, unrecoverable error occured during allocation (unexpected) |
| */ |
| virtual C2Error allocateLinearBuffer( |
| uint32_t capacity __unused, C2MemoryUsage usage __unused, |
| std::shared_ptr<C2LinearAllocation> *allocation /* nonnull */) { |
| *allocation = nullptr; |
| return C2_UNSUPPORTED; |
| } |
| |
| /** |
| * (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 |
| * \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_NO_PERMISSION no permission to recreate the allocation |
| * \retval C2_BAD_VALUE invalid handle (caller error) |
| * \retval C2_UNSUPPORTED this allocator does not support 1D allocations |
| * \retval C2_CORRUPTED some unknown, unrecoverable error occured during allocation (unexpected) |
| */ |
| virtual C2Error recreateLinearBuffer( |
| const C2Handle *handle __unused, |
| std::shared_ptr<C2LinearAllocation> *allocation /* nonnull */) { |
| *allocation = nullptr; |
| return C2_UNSUPPORTED; |
| } |
| |
| /** |
| * 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_NO_PERMISSION no permission to complete the allocation |
| * \retval C2_BAD_VALUE width, height, format or usage are not supported (invalid) (caller error) |
| * \retval C2_UNSUPPORTED this allocator does not support 2D allocations |
| * \retval C2_CORRUPTED some unknown, unrecoverable error occured during allocation (unexpected) |
| */ |
| virtual C2Error allocateGraphicBuffer( |
| 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_UNSUPPORTED; |
| } |
| |
| /** |
| * (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 |
| * \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_NO_PERMISSION no permission to recreate the allocation |
| * \retval C2_BAD_VALUE invalid handle (caller error) |
| * \retval C2_UNSUPPORTED this allocator does not support 2D allocations |
| * \retval C2_CORRUPTED some unknown, unrecoverable error occured during recreation (unexpected) |
| */ |
| virtual C2Error recreateGraphicBuffer( |
| const C2Handle *handle __unused, |
| std::shared_ptr<C2GraphicAllocation> *allocation /* nonnull */) { |
| *allocation = nullptr; |
| return C2_UNSUPPORTED; |
| } |
| |
| protected: |
| C2Allocator() = default; |
| |
| virtual ~C2Allocator() = default; |
| }; |
| |
| /** |
| * Block allocators are used by components to allocate memory for output buffers. They can |
| * support either linear (1D), circular (1D) or graphic (2D) allocations. |
| * |
| * Never constructed on stack. |
| * |
| * Block allocators are provided by the framework. |
| */ |
| class C2BlockAllocator { |
| public: |
| /** |
| * Allocates 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 allocation. \note that the |
| * returned allocation may be later used/mapped with different usage. |
| * The allocator shall lay out 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 block pointer to where the allocated block 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_NO_PERMISSION no permission to complete the allocation |
| * \retval C2_BAD_VALUE capacity or usage are not supported (invalid) (caller error) |
| * \retval C2_UNSUPPORTED this allocator does not support linear allocations |
| * \retval C2_CORRUPTED some unknown, unrecoverable error occured during allocation (unexpected) |
| */ |
| virtual C2Error allocateLinearBlock( |
| uint32_t capacity __unused, C2MemoryUsage usage __unused, |
| std::shared_ptr<C2LinearBlock> *block /* nonnull */) { |
| *block = nullptr; |
| return C2_UNSUPPORTED; |
| } |
| |
| /** |
| * Allocates 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. (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 shall lay out 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 block pointer to where the allocated block 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_NO_PERMISSION no permission to complete the allocation |
| * \retval C2_BAD_VALUE capacity or usage are not supported (invalid) (caller error) |
| * \retval C2_UNSUPPORTED this allocator does not support circular allocations |
| * \retval C2_CORRUPTED some unknown, unrecoverable error occured during allocation (unexpected) |
| */ |
| virtual C2Error allocateCircularBlock( |
| uint32_t capacity __unused, C2MemoryUsage usage __unused, |
| std::shared_ptr<C2CircularBlock> *block /* nonnull */) { |
| *block = nullptr; |
| return C2_UNSUPPORTED; |
| } |
| |
| /** |
| * Allocates a 2D graphic block of given |width|, |height|, |format| and |usage|. If successful, |
| * the allocation is stored in |block|. Otherwise, |block| 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 block 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_NO_PERMISSION no permission to complete the allocation |
| * \retval C2_BAD_VALUE width, height, format or usage are not supported (invalid) (caller error) |
| * \retval C2_UNSUPPORTED this allocator does not support 2D allocations |
| * \retval C2_CORRUPTED some unknown, unrecoverable error occured during allocation (unexpected) |
| */ |
| virtual C2Error allocateGraphicBlock( |
| 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_UNSUPPORTED; |
| } |
| |
| protected: |
| C2BlockAllocator() = default; |
| |
| virtual ~C2BlockAllocator() = default; |
| }; |
| |
| /// @} |
| |
| /// \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 |
| |
| /// @} |
| |
| } // namespace android |
| |
| #endif // C2BUFFER_H_ |
