| /* |
| * 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 C2PARAM_H_ |
| #define C2PARAM_H_ |
| |
| #include <C2.h> |
| |
| #include <stdbool.h> |
| #include <stdint.h> |
| |
| #include <algorithm> |
| #include <list> |
| #include <string> |
| #include <type_traits> |
| |
| #define C2_PACK __attribute__((packed)) |
| |
| namespace android { |
| |
| /// \addtogroup Parameters |
| /// @{ |
| |
| /// \defgroup internal Internal helpers. |
| |
| /*! |
| * \file |
| * PARAMETERS: SETTINGs, TUNINGs, and INFOs |
| * === |
| * |
| * These represent miscellaneous control and metadata information and are likely copied into |
| * kernel space. Therefore, these are C-like structures designed to carry just a small amount of |
| * information. We are using C++ to be able to add constructors, as well as non-virtual and class |
| * methods. |
| * |
| * ==Specification details: |
| * |
| * Restrictions: |
| * - must be POD struct, e.g. no vtable (no virtual destructor) |
| * - must have the same size in 64-bit and 32-bit mode (no size_t) |
| * - as such, no pointer members |
| * |
| * Behavior: |
| * - Params can be global (not related to input or output), related to input or output, |
| * or related to an input/output stream. |
| * - All params are queried/set using a unique param index, which incorporates a potential stream |
| * index and/or port. |
| * - Querying (supported) params MUST never fail. |
| * - All params MUST have default values. |
| * - If some fields have "unsupported" or "invalid" values during setting, this SHOULD be |
| * communicated to the app. |
| * a) Ideally, this should be avoided. When setting parameters, in general, component should do |
| * "best effort" to apply all settings. It should change "invalid/unsupported" values to the |
| * nearest supported values. |
| * - This is communicated to the client by changing the source values in tune()/ |
| * configure(). |
| * b) If falling back to a supported value is absolutely impossible, the component SHALL return |
| * an error for the specific setting, but should continue to apply other settings. |
| * TODO: this currently may result in unintended results. |
| * |
| * **NOTE:** unlike OMX, params are not versioned. Instead, a new struct with new base index |
| * SHALL be added as new versions are required. |
| * |
| * The proper subtype (Setting, Info or Param) is incorporated into the class type. Define structs |
| * to define multiple subtyped versions of related parameters. |
| * |
| * ==Implementation details: |
| * |
| * - Use macros to define parameters |
| * - All parameters must have a default constructor |
| * - This is only used for instantiating the class in source (e.g. will not be used |
| * when building a parameter by the framework from key/value pairs.) |
| */ |
| |
| /// \ingroup internal |
| struct _C2ParamManipulator; |
| |
| /** |
| * Parameter base class. |
| */ |
| struct C2Param { |
| // param index encompasses the following: |
| // |
| // - type (setting, tuning, info, struct) |
| // - vendor extension flag |
| // - flexible parameter flag |
| // - direction (global, input, output) |
| // - stream flag |
| // - stream ID (usually 0) |
| // |
| // layout: |
| // |
| // +------+-----+---+------+--------+----|------+--------------+ |
| // | kind | dir | - |stream|streamID|flex|vendor| base index | |
| // +------+-----+---+------+--------+----+------+--------------+ |
| // bit: 31..30 29.28 25 24 .. 17 16 15 14 .. 0 |
| // |
| public: |
| /** |
| * C2Param kinds, usable as bitmaps. |
| */ |
| enum Kind : uint32_t { |
| NONE = 0, |
| STRUCT = (1 << 0), |
| INFO = (1 << 1), |
| SETTING = (1 << 2), |
| TUNING = (1 << 3) | SETTING, // tunings are settings |
| }; |
| |
| /** |
| * base index (including the vendor extension bit) is a global index for |
| * C2 parameter structs. (e.g. the same indices cannot be reused for different |
| * structs for different components). |
| */ |
| struct BaseIndex { |
| protected: |
| enum : uint32_t { |
| kTypeMask = 0xC0000000, |
| kTypeStruct = 0x00000000, |
| kTypeTuning = 0x40000000, |
| kTypeSetting = 0x80000000, |
| kTypeInfo = 0xC0000000, |
| |
| kDirMask = 0x30000000, |
| kDirGlobal = 0x20000000, |
| kDirUndefined = 0x30000000, // MUST have all bits set |
| kDirInput = 0x00000000, |
| kDirOutput = 0x10000000, |
| |
| kStreamFlag = 0x02000000, |
| kStreamIdMask = 0x01FE0000, |
| kStreamIdShift = 17, |
| kStreamIdMax = kStreamIdMask >> kStreamIdShift, |
| kStreamMask = kStreamFlag | kStreamIdMask, |
| |
| kFlexibleFlag = 0x00010000, |
| kVendorFlag = 0x00008000, |
| kParamMask = 0x0000FFFF, |
| kBaseMask = kParamMask | kFlexibleFlag, |
| }; |
| |
| public: |
| enum : uint32_t { |
| kVendorStart = kVendorFlag, ///< vendor structs SHALL start after this |
| _kFlexibleFlag = kFlexibleFlag, // TODO: this is only needed for testing |
| }; |
| |
| /// constructor/conversion from uint32_t |
| inline BaseIndex(uint32_t index) : mIndex(index) { } |
| |
| // no conversion from uint64_t |
| inline BaseIndex(uint64_t index) = delete; |
| |
| /// returns true iff this is a vendor extension parameter |
| inline bool isVendor() const { return mIndex & kVendorFlag; } |
| |
| /// returns true iff this is a flexible parameter (with variable size) |
| inline bool isFlexible() const { return mIndex & kFlexibleFlag; } |
| |
| /// returns the base type: the index for the underlying struct |
| inline unsigned int baseIndex() const { return mIndex & kBaseMask; } |
| |
| /// returns the param index for the underlying struct |
| inline unsigned int paramIndex() const { return mIndex & kParamMask; } |
| |
| DEFINE_FIELD_BASED_COMPARISON_OPERATORS(BaseIndex, mIndex) |
| |
| protected: |
| uint32_t mIndex; |
| }; |
| |
| /** |
| * type encompasses the parameter kind (tuning, setting, info), whether the |
| * parameter is global, input or output, and whether it is for a stream. |
| */ |
| struct Type : public BaseIndex { |
| /// returns true iff this is a global parameter (not for input nor output) |
| inline bool isGlobal() const { return (mIndex & kDirMask) == kDirGlobal; } |
| /// returns true iff this is an input or input stream parameter |
| inline bool forInput() const { return (mIndex & kDirMask) == kDirInput; } |
| /// returns true iff this is an output or output stream parameter |
| inline bool forOutput() const { return (mIndex & kDirMask) == kDirOutput; } |
| |
| /// returns true iff this is a stream parameter |
| inline bool forStream() const { return mIndex & kStreamFlag; } |
| /// returns true iff this is a port (input or output) parameter |
| inline bool forPort() const { return !forStream() && !isGlobal(); } |
| |
| /// returns the parameter type: the parameter index without the stream ID |
| inline uint32_t type() const { return mIndex & (~kStreamIdMask); } |
| |
| /// return the kind of this param |
| inline Kind kind() const { |
| switch (mIndex & kTypeMask) { |
| case kTypeStruct: return STRUCT; |
| case kTypeInfo: return INFO; |
| case kTypeSetting: return SETTING; |
| case kTypeTuning: return TUNING; |
| default: return NONE; // should not happen |
| } |
| } |
| |
| /// constructor/conversion from uint32_t |
| inline Type(uint32_t index) : BaseIndex(index) { } |
| |
| // no conversion from uint64_t |
| inline Type(uint64_t index) = delete; |
| |
| private: |
| friend struct C2Param; // for setPort() |
| friend struct C2Tuning; // for kTypeTuning |
| friend struct C2Setting; // for kTypeSetting |
| friend struct C2Info; // for kTypeInfo |
| // for kDirGlobal |
| template<typename T, typename S, int I, class F> friend struct C2GlobalParam; |
| template<typename T, typename S, int I, class F> friend struct C2PortParam; // for kDir* |
| template<typename T, typename S, int I, class F> friend struct C2StreamParam; // for kDir* |
| friend struct _C2ParamInspector; // for testing |
| |
| /** |
| * Sets the port/stream direction. |
| * @return true on success, false if could not set direction (e.g. it is global param). |
| */ |
| inline bool setPort(bool output) { |
| if (isGlobal()) { |
| return false; |
| } else { |
| mIndex = (mIndex & ~kDirMask) | (output ? kDirOutput : kDirInput); |
| return true; |
| } |
| } |
| }; |
| |
| /** |
| * index encompasses all remaining information: basically the stream ID. |
| */ |
| struct Index : public Type { |
| /// returns the index as uint32_t |
| inline operator uint32_t() const { return mIndex; } |
| |
| /// constructor/conversion from uint32_t |
| inline Index(uint32_t index) : Type(index) { } |
| |
| // no conversion from uint64_t |
| inline Index(uint64_t index) = delete; |
| |
| /// returns the stream ID or ~0 if not a stream |
| inline unsigned stream() const { |
| return forStream() ? rawStream() : ~0U; |
| } |
| |
| private: |
| friend struct C2Param; // for setStream, makeStreamId, isValid |
| friend struct _C2ParamInspector; // for testing |
| |
| /** |
| * @return true if the type is valid, e.g. direction is not undefined AND |
| * stream is 0 if not a stream param. |
| */ |
| inline bool isValid() const { |
| // there is no Type::isValid (even though some of this check could be |
| // performed on types) as this is only used on index... |
| return (forStream() ? rawStream() < kStreamIdMax : rawStream() == 0) |
| && (mIndex & kDirMask) != kDirUndefined; |
| } |
| |
| /// returns the raw stream ID field |
| inline unsigned rawStream() const { |
| return (mIndex & kStreamIdMask) >> kStreamIdShift; |
| } |
| |
| /// returns the streamId bitfield for a given |stream|. If stream is invalid, |
| /// returns an invalid bitfield. |
| inline static uint32_t makeStreamId(unsigned stream) { |
| // saturate stream ID (max value is invalid) |
| if (stream > kStreamIdMax) { |
| stream = kStreamIdMax; |
| } |
| return (stream << kStreamIdShift) & kStreamIdMask; |
| } |
| |
| /** |
| * Sets the stream index. |
| * \return true on success, false if could not set index (e.g. not a stream param). |
| */ |
| inline bool setStream(unsigned stream) { |
| if (forStream()) { |
| mIndex = (mIndex & ~kStreamIdMask) | makeStreamId(stream); |
| return this->stream() < kStreamIdMax; |
| } |
| return false; |
| } |
| }; |
| |
| public: |
| // public getters for Index methods |
| |
| /// returns true iff this is a vendor extension parameter |
| inline bool isVendor() const { return _mIndex.isVendor(); } |
| /// returns true iff this is a flexible parameter |
| inline bool isFlexible() const { return _mIndex.isFlexible(); } |
| /// returns true iff this is a global parameter (not for input nor output) |
| inline bool isGlobal() const { return _mIndex.isGlobal(); } |
| /// returns true iff this is an input or input stream parameter |
| inline bool forInput() const { return _mIndex.forInput(); } |
| /// returns true iff this is an output or output stream parameter |
| inline bool forOutput() const { return _mIndex.forOutput(); } |
| |
| /// returns true iff this is a stream parameter |
| inline bool forStream() const { return _mIndex.forStream(); } |
| /// returns true iff this is a port (input or output) parameter |
| inline bool forPort() const { return _mIndex.forPort(); } |
| |
| /// returns the stream ID or ~0 if not a stream |
| inline unsigned stream() const { return _mIndex.stream(); } |
| |
| /// returns the parameter type: the parameter index without the stream ID |
| inline uint32_t type() const { return _mIndex.type(); } |
| |
| /// returns the kind of this parameter |
| inline Kind kind() const { return _mIndex.kind(); } |
| |
| /// returns the size of the parameter or 0 if the parameter is invalid |
| inline size_t size() const { return _mSize; } |
| |
| /// returns true iff the parameter is valid |
| inline operator bool() const { return _mIndex.isValid() && _mSize > 0; } |
| |
| /// returns true iff the parameter is invalid |
| inline bool operator!() const { return !operator bool(); } |
| |
| // equality is done by memcmp (use equals() to prevent any overread) |
| inline bool operator==(const C2Param &o) const { |
| return equals(o) && memcmp(this, &o, _mSize) == 0; |
| } |
| inline bool operator!=(const C2Param &o) const { return !operator==(o); } |
| |
| /// safe(r) type cast from pointer and size |
| inline static C2Param* From(void *addr, size_t len) { |
| // _mSize must fit into size |
| if (len < sizeof(_mSize) + offsetof(C2Param, _mSize)) { |
| return nullptr; |
| } |
| // _mSize must match length |
| C2Param *param = (C2Param*)addr; |
| if (param->_mSize != len) { |
| return nullptr; |
| } |
| return param; |
| } |
| |
| #if 0 |
| template<typename P, class=decltype(C2Param(P()))> |
| P *As() { return P::From(this); } |
| template<typename P> |
| const P *As() const { return const_cast<const P*>(P::From(const_cast<C2Param*>(this))); } |
| #endif |
| |
| protected: |
| /// sets the stream field. Returns true iff successful. |
| inline bool setStream(unsigned stream) { |
| return _mIndex.setStream(stream); |
| } |
| |
| /// sets the port (direction). Returns true iff successful. |
| inline bool setPort(bool output) { |
| return _mIndex.setPort(output); |
| } |
| |
| public: |
| /// invalidate this parameter. There is no recovery from this call; e.g. parameter |
| /// cannot be 'corrected' to be valid. |
| inline void invalidate() { _mSize = 0; } |
| |
| // if other is the same kind of (valid) param as this, copy it into this and return true. |
| // otherwise, do not copy anything, and return false. |
| inline bool updateFrom(const C2Param &other) { |
| if (other._mSize == _mSize && other._mIndex == _mIndex && _mSize > 0) { |
| memcpy(this, &other, _mSize); |
| return true; |
| } |
| return false; |
| } |
| |
| protected: |
| // returns |o| if it is a null ptr, or if can suitably be a param of given |type| (e.g. has |
| // same type (ignoring stream ID), and size). Otherwise, returns null. If |checkDir| is false, |
| // allow undefined or different direction (e.g. as constructed from C2PortParam() vs. |
| // C2PortParam::input), but still require equivalent type (stream, port or global); otherwise, |
| // return null. |
| inline static const C2Param* ifSuitable( |
| const C2Param* o, size_t size, Type type, size_t flexSize = 0, bool checkDir = true) { |
| if (o == nullptr || o->_mSize < size || (flexSize && ((o->_mSize - size) % flexSize))) { |
| return nullptr; |
| } else if (checkDir) { |
| return o->_mIndex.type() == type.mIndex ? o : nullptr; |
| } else if (o->_mIndex.isGlobal()) { |
| return nullptr; |
| } else { |
| return ((o->_mIndex.type() ^ type.mIndex) & ~Type::kDirMask) ? nullptr : o; |
| } |
| } |
| |
| /// base constructor |
| inline C2Param(uint32_t paramSize, Index paramIndex) |
| : _mSize(paramSize), |
| _mIndex(paramIndex) { |
| if (paramSize > sizeof(C2Param)) { |
| memset(this + 1, 0, paramSize - sizeof(C2Param)); |
| } |
| } |
| |
| /// base constructor with stream set |
| inline C2Param(uint32_t paramSize, Index paramIndex, unsigned stream) |
| : _mSize(paramSize), |
| _mIndex(paramIndex | Index::makeStreamId(stream)) { |
| if (paramSize > sizeof(C2Param)) { |
| memset(this + 1, 0, paramSize - sizeof(C2Param)); |
| } |
| if (!forStream()) { |
| invalidate(); |
| } |
| } |
| |
| private: |
| friend struct _C2ParamInspector; // for testing |
| |
| /// returns the base type: the index for the underlying struct (for testing |
| /// as this can be gotten by the baseIndex enum) |
| inline uint32_t _baseIndex() const { return _mIndex.baseIndex(); } |
| |
| /// returns true iff |o| has the same size and index as this. This performs the |
| /// basic check for equality. |
| inline bool equals(const C2Param &o) const { |
| return _mSize == o._mSize && _mIndex == o._mIndex; |
| } |
| |
| uint32_t _mSize; |
| Index _mIndex; |
| }; |
| |
| /// \ingroup internal |
| /// allow C2Params access to private methods, e.g. constructors |
| #define C2PARAM_MAKE_FRIENDS \ |
| template<typename U, typename S, int I, class F> friend struct C2GlobalParam; \ |
| template<typename U, typename S, int I, class F> friend struct C2PortParam; \ |
| template<typename U, typename S, int I, class F> friend struct C2StreamParam; \ |
| |
| /** |
| * Setting base structure for component method signatures. Wrap constructors. |
| */ |
| struct C2Setting : public C2Param { |
| protected: |
| template<typename ...Args> |
| inline C2Setting(const Args(&... args)) : C2Param(args...) { } |
| public: // TODO |
| enum : uint32_t { indexFlags = Type::kTypeSetting }; |
| }; |
| |
| /** |
| * Tuning base structure for component method signatures. Wrap constructors. |
| */ |
| struct C2Tuning : public C2Setting { |
| protected: |
| template<typename ...Args> |
| inline C2Tuning(const Args(&... args)) : C2Setting(args...) { } |
| public: // TODO |
| enum : uint32_t { indexFlags = Type::kTypeTuning }; |
| }; |
| |
| /** |
| * Info base structure for component method signatures. Wrap constructors. |
| */ |
| struct C2Info : public C2Param { |
| protected: |
| template<typename ...Args> |
| inline C2Info(const Args(&... args)) : C2Param(args...) { } |
| public: // TODO |
| enum : uint32_t { indexFlags = Type::kTypeInfo }; |
| }; |
| |
| /** |
| * Structure uniquely specifying a field in an arbitrary structure. |
| * |
| * \note This structure is used differently in C2FieldDescriptor to |
| * identify array fields, such that _mSize is the size of each element. This is |
| * because the field descriptor contains the array-length, and we want to keep |
| * a relevant element size for variable length arrays. |
| */ |
| struct _C2FieldId { |
| //public: |
| /** |
| * Constructor used for C2FieldDescriptor that removes the array extent. |
| * |
| * \param[in] offset pointer to the field in an object at address 0. |
| */ |
| template<typename T, class B=typename std::remove_extent<T>::type> |
| inline _C2FieldId(T* offset) |
| : // offset is from "0" so will fit on 32-bits |
| _mOffset((uint32_t)(uintptr_t)(offset)), |
| _mSize(sizeof(B)) { } |
| |
| /** |
| * Direct constructor from offset and size. |
| * |
| * \param[in] offset offset of the field. |
| * \param[in] size size of the field. |
| */ |
| inline _C2FieldId(size_t offset, size_t size) |
| : _mOffset(offset), _mSize(size) {} |
| |
| /** |
| * Constructor used to identify a field in an object. |
| * |
| * \param U[type] pointer to the object that contains this field. This is needed in case the |
| * field is in an (inherited) base class, in which case T will be that base class. |
| * \param pm[im] member pointer to the field |
| */ |
| template<typename R, typename T, typename U, typename B=typename std::remove_extent<R>::type> |
| inline _C2FieldId(U *, R T::* pm) |
| : _mOffset((uint32_t)(uintptr_t)(&(((U*)256)->*pm)) - 256u), |
| _mSize(sizeof(B)) { } |
| |
| /** |
| * Constructor used to identify a field in an object. |
| * |
| * \param U[type] pointer to the object that contains this field |
| * \param pm[im] member pointer to the field |
| */ |
| template<typename R, typename T, typename B=typename std::remove_extent<R>::type> |
| inline _C2FieldId(R T::* pm) |
| : _mOffset((uint32_t)(uintptr_t)(&(((T*)0)->*pm))), |
| _mSize(sizeof(B)) { } |
| |
| inline bool operator==(const _C2FieldId &other) const { |
| return _mOffset == other._mOffset && _mSize == other._mSize; |
| } |
| |
| inline bool operator<(const _C2FieldId &other) const { |
| return _mOffset < other._mOffset || |
| // NOTE: order parent structure before sub field |
| (_mOffset == other._mOffset && _mSize > other._mSize); |
| } |
| |
| DEFINE_OTHER_COMPARISON_OPERATORS(_C2FieldId) |
| |
| #if 0 |
| inline uint32_t offset() const { return _mOffset; } |
| inline uint32_t size() const { return _mSize; } |
| #endif |
| |
| #if defined(FRIEND_TEST) |
| friend void PrintTo(const _C2FieldId &d, ::std::ostream*); |
| #endif |
| |
| private: |
| uint32_t _mOffset; // offset of field |
| uint32_t _mSize; // size of field |
| }; |
| |
| /** |
| * Structure uniquely specifying a field in a configuration |
| */ |
| struct C2ParamField { |
| //public: |
| // TODO: fix what this is for T[] (for now size becomes T[1]) |
| template<typename S, typename T> |
| inline C2ParamField(S* param, T* offset) |
| : _mIndex(param->index()), |
| _mFieldId(offset) {} |
| |
| template<typename R, typename T, typename U> |
| inline C2ParamField(U *p, R T::* pm) : _mIndex(p->type()), _mFieldId(p, pm) { } |
| |
| inline bool operator==(const C2ParamField &other) const { |
| return _mIndex == other._mIndex && _mFieldId == other._mFieldId; |
| } |
| |
| inline bool operator<(const C2ParamField &other) const { |
| return _mIndex < other._mIndex || |
| (_mIndex == other._mIndex && _mFieldId < other._mFieldId); |
| } |
| |
| DEFINE_OTHER_COMPARISON_OPERATORS(C2ParamField) |
| |
| private: |
| C2Param::Index _mIndex; |
| _C2FieldId _mFieldId; |
| }; |
| |
| /** |
| * A shared (union) representation of numeric values |
| */ |
| class C2Value { |
| public: |
| /// A union of supported primitive types. |
| union Primitive { |
| int32_t i32; ///< int32_t value |
| uint32_t u32; ///< uint32_t value |
| int64_t i64; ///< int64_t value |
| uint64_t u64; ///< uint64_t value |
| float fp; ///< float value |
| |
| // constructors - implicit |
| Primitive(int32_t value) : i32(value) { } |
| Primitive(uint32_t value) : u32(value) { } |
| Primitive(int64_t value) : i64(value) { } |
| Primitive(uint64_t value) : u64(value) { } |
| Primitive(float value) : fp(value) { } |
| |
| Primitive() : u64(0) { } |
| |
| private: |
| friend class C2Value; |
| template<typename T> const T &ref() const; |
| }; |
| |
| enum Type { |
| NO_INIT, |
| INT32, |
| UINT32, |
| INT64, |
| UINT64, |
| FLOAT, |
| }; |
| |
| template<typename T> static constexpr Type typeFor(); |
| |
| // constructors - implicit |
| template<typename T> |
| C2Value(T value) : mType(typeFor<T>()), mValue(value) { } |
| |
| C2Value() : mType(NO_INIT) { } |
| |
| inline Type type() const { return mType; } |
| |
| template<typename T> |
| inline bool get(T *value) const { |
| if (mType == typeFor<T>()) { |
| *value = mValue.ref<T>(); |
| return true; |
| } |
| return false; |
| } |
| |
| private: |
| Type mType; |
| Primitive mValue; |
| }; |
| |
| template<> const int32_t &C2Value::Primitive::ref<int32_t>() const { return i32; } |
| template<> const int64_t &C2Value::Primitive::ref<int64_t>() const { return i64; } |
| template<> const uint32_t &C2Value::Primitive::ref<uint32_t>() const { return u32; } |
| template<> const uint64_t &C2Value::Primitive::ref<uint64_t>() const { return u64; } |
| template<> const float &C2Value::Primitive::ref<float>() const { return fp; } |
| |
| template<> constexpr C2Value::Type C2Value::typeFor<int32_t>() { return INT32; } |
| template<> constexpr C2Value::Type C2Value::typeFor<int64_t>() { return INT64; } |
| template<> constexpr C2Value::Type C2Value::typeFor<uint32_t>() { return UINT32; } |
| template<> constexpr C2Value::Type C2Value::typeFor<uint64_t>() { return UINT64; } |
| template<> constexpr C2Value::Type C2Value::typeFor<float>() { return FLOAT; } |
| |
| /** |
| * field descriptor. A field is uniquely defined by an index into a parameter. |
| * (Note: Stream-id is not captured as a field.) |
| * |
| * Ordering of fields is by offset. In case of structures, it is depth first, |
| * with a structure taking an index just before and in addition to its members. |
| */ |
| struct C2FieldDescriptor { |
| //public: |
| /** field types and flags |
| * \note: only 32-bit and 64-bit fields are supported (e.g. no boolean, as that |
| * is represented using INT32). |
| */ |
| enum Type : uint32_t { |
| // primitive types |
| INT32 = C2Value::INT32, ///< 32-bit signed integer |
| UINT32 = C2Value::UINT32, ///< 32-bit unsigned integer |
| INT64 = C2Value::INT64, ///< 64-bit signed integer |
| UINT64 = C2Value::UINT64, ///< 64-bit signed integer |
| FLOAT = C2Value::FLOAT, ///< 32-bit floating point |
| |
| // array types |
| STRING = 0x100, ///< fixed-size string (POD) |
| BLOB, ///< blob. Blobs have no sub-elements and can be thought of as byte arrays; |
| ///< however, bytes cannot be individually addressed by clients. |
| |
| // complex types |
| STRUCT_FLAG = 0x10000, ///< structs. Marked with this flag in addition to their baseIndex. |
| }; |
| |
| typedef std::pair<C2String, C2Value::Primitive> named_value_type; |
| typedef std::vector<const named_value_type> named_values_type; |
| //typedef std::pair<std::vector<C2String>, std::vector<C2Value::Primitive>> named_values_type; |
| |
| /** |
| * Template specialization that returns the named values for a type. |
| * |
| * \todo hide from client. |
| * |
| * \return a vector of name-value pairs. |
| */ |
| template<typename B> |
| static named_values_type namedValuesFor(const B &); |
| |
| inline C2FieldDescriptor(uint32_t type, uint32_t length, C2StringLiteral name, size_t offset, size_t size) |
| : _mType((Type)type), _mLength(length), _mName(name), _mFieldId(offset, size) { } |
| |
| template<typename T, class B=typename std::remove_extent<T>::type> |
| inline C2FieldDescriptor(const T* offset, const char *name) |
| : _mType(this->getType((B*)nullptr)), |
| _mLength(std::is_array<T>::value ? std::extent<T>::value : 1), |
| _mName(name), |
| _mNamedValues(namedValuesFor(*(B*)0)), |
| _mFieldId(offset) {} |
| |
| /* |
| template<typename T, typename B=typename std::remove_extent<T>::type> |
| inline C2FieldDescriptor<T, B, false>(T* offset, const char *name) |
| : _mType(this->getType((B*)nullptr)), |
| _mLength(std::is_array<T>::value ? std::extent<T>::value : 1), |
| _mName(name), |
| _mFieldId(offset) {} |
| */ |
| |
| /// \deprecated |
| template<typename T, typename S, class B=typename std::remove_extent<T>::type> |
| constexpr inline C2FieldDescriptor(S*, T S::* field, const char *name) |
| : _mType(this->getType((B*)nullptr)), |
| _mLength(std::is_array<T>::value ? std::extent<T>::value : 1), |
| _mName(name), |
| _mFieldId(&(((S*)0)->*field)) {} |
| |
| /// returns the type of this field |
| inline Type type() const { return _mType; } |
| /// returns the length of the field in case it is an array. Returns 0 for |
| /// T[] arrays, returns 1 for T[1] arrays as well as if the field is not an array. |
| inline size_t length() const { return _mLength; } |
| /// returns the name of the field |
| inline C2StringLiteral name() const { return _mName; } |
| |
| const named_values_type &namedValues() const { return _mNamedValues; } |
| |
| #if defined(FRIEND_TEST) |
| friend void PrintTo(const C2FieldDescriptor &, ::std::ostream*); |
| friend bool operator==(const C2FieldDescriptor &, const C2FieldDescriptor &); |
| FRIEND_TEST(C2ParamTest_ParamFieldList, VerifyStruct); |
| #endif |
| |
| private: |
| const Type _mType; |
| const uint32_t _mLength; // the last member can be arbitrary length if it is T[] array, |
| // extending to the end of the parameter (this is marked with |
| // 0). T[0]-s are not fields. |
| const C2StringLiteral _mName; |
| const named_values_type _mNamedValues; |
| |
| const _C2FieldId _mFieldId; // field identifier (offset and size) |
| |
| // NOTE: We do not capture default value(s) here as that may depend on the component. |
| // NOTE: We also do not capture bestEffort, as 1) this should be true for most fields, |
| // 2) this is at parameter granularity. |
| |
| // type resolution |
| inline static Type getType(int32_t*) { return INT32; } |
| inline static Type getType(uint32_t*) { return UINT32; } |
| inline static Type getType(int64_t*) { return INT64; } |
| inline static Type getType(uint64_t*) { return UINT64; } |
| inline static Type getType(float*) { return FLOAT; } |
| inline static Type getType(char*) { return STRING; } |
| inline static Type getType(uint8_t*) { return BLOB; } |
| |
| template<typename T, |
| class=typename std::enable_if<std::is_enum<T>::value>::type> |
| inline static Type getType(T*) { |
| typename std::underlying_type<T>::type underlying(0); |
| return getType(&underlying); |
| } |
| |
| // verify C2Struct by having a fieldList and a baseIndex. |
| template<typename T, |
| class=decltype(T::baseIndex + 1), class=decltype(T::fieldList)> |
| inline static Type getType(T*) { |
| static_assert(!std::is_base_of<C2Param, T>::value, "cannot use C2Params as fields"); |
| return (Type)(T::baseIndex | STRUCT_FLAG); |
| } |
| }; |
| |
| #define DEFINE_NO_NAMED_VALUES_FOR(type) \ |
| template<> inline C2FieldDescriptor::named_values_type C2FieldDescriptor::namedValuesFor(const type &) { \ |
| return named_values_type(); \ |
| } |
| |
| // We cannot subtype constructor for enumerated types so insted define no named values for |
| // non-enumerated integral types. |
| DEFINE_NO_NAMED_VALUES_FOR(int32_t) |
| DEFINE_NO_NAMED_VALUES_FOR(uint32_t) |
| DEFINE_NO_NAMED_VALUES_FOR(int64_t) |
| DEFINE_NO_NAMED_VALUES_FOR(uint64_t) |
| DEFINE_NO_NAMED_VALUES_FOR(uint8_t) |
| DEFINE_NO_NAMED_VALUES_FOR(char) |
| DEFINE_NO_NAMED_VALUES_FOR(float) |
| |
| /** |
| * Describes the fields of a structure. |
| */ |
| struct C2StructDescriptor { |
| public: |
| /// Returns the parameter type |
| inline C2Param::BaseIndex baseIndex() const { return _mType.baseIndex(); } |
| |
| // Returns the number of fields in this param (not counting any recursive fields). |
| // Must be at least 1 for valid params. |
| inline size_t numFields() const { return _mFields.size(); } |
| |
| // Returns the list of immediate fields (not counting any recursive fields). |
| typedef std::vector<const C2FieldDescriptor>::const_iterator field_iterator; |
| inline field_iterator cbegin() const { return _mFields.cbegin(); } |
| inline field_iterator cend() const { return _mFields.cend(); } |
| |
| // only supplying const iterator - but these are needed for range based loops |
| inline field_iterator begin() const { return _mFields.cbegin(); } |
| inline field_iterator end() const { return _mFields.cend(); } |
| |
| template<typename T> |
| inline C2StructDescriptor(T*) |
| : C2StructDescriptor(T::baseIndex, T::fieldList) { } |
| |
| inline C2StructDescriptor( |
| C2Param::BaseIndex type, |
| std::initializer_list<const C2FieldDescriptor> fields) |
| : _mType(type), _mFields(fields) { } |
| |
| private: |
| const C2Param::BaseIndex _mType; |
| const std::vector<const C2FieldDescriptor> _mFields; |
| }; |
| |
| /** |
| * Describes parameters for a component. |
| */ |
| struct C2ParamDescriptor { |
| public: |
| /** |
| * Returns whether setting this param is required to configure this component. |
| * This can only be true for builtin params for platform-defined components (e.g. video and |
| * audio encoders/decoders, video/audio filters). |
| * For vendor-defined components, it can be true even for vendor-defined params, |
| * but it is not recommended, in case the component becomes platform-defined. |
| */ |
| inline bool isRequired() const { return _mIsRequired; } |
| |
| /** |
| * Returns whether this parameter is persistent. This is always true for C2Tuning and C2Setting, |
| * but may be false for C2Info. If true, this parameter persists across frames and applies to |
| * the current and subsequent frames. If false, this C2Info parameter only applies to the |
| * current frame and is not assumed to have the same value (or even be present) on subsequent |
| * frames, unless it is specified for those frames. |
| */ |
| inline bool isPersistent() const { return _mIsPersistent; } |
| |
| /// Returns the name of this param. |
| /// This defaults to the underlying C2Struct's name, but could be altered for a component. |
| inline C2String name() const { return _mName; } |
| |
| /// Returns the parameter type |
| /// \todo fix this |
| inline C2Param::Type type() const { return _mType; } |
| |
| template<typename T> |
| inline C2ParamDescriptor(bool isRequired, C2StringLiteral name, const T*) |
| : _mIsRequired(isRequired), |
| _mIsPersistent(true), |
| _mName(name), |
| _mType(T::typeIndex) { } |
| |
| inline C2ParamDescriptor( |
| bool isRequired, C2StringLiteral name, C2Param::Type type) |
| : _mIsRequired(isRequired), |
| _mIsPersistent(true), |
| _mName(name), |
| _mType(type) { } |
| |
| private: |
| const bool _mIsRequired; |
| const bool _mIsPersistent; |
| const C2String _mName; |
| const C2Param::Type _mType; |
| }; |
| |
| /// \ingroup internal |
| /// Define a structure without baseIndex. |
| #define DEFINE_C2STRUCT_NO_BASE(name) \ |
| public: \ |
| typedef C2##name##Struct _type; /**< type name shorthand */ \ |
| const static std::initializer_list<const C2FieldDescriptor> fieldList; /**< structure fields */ |
| |
| /// Define a structure with matching baseIndex. |
| #define DEFINE_C2STRUCT(name) \ |
| public: \ |
| enum : uint32_t { baseIndex = kParamIndex##name }; \ |
| DEFINE_C2STRUCT_NO_BASE(name) |
| |
| /// Define a flexible structure with matching baseIndex. |
| #define DEFINE_FLEX_C2STRUCT(name, flexMember) \ |
| public: \ |
| FLEX(C2##name##Struct, flexMember) \ |
| enum : uint32_t { baseIndex = kParamIndex##name | C2Param::BaseIndex::_kFlexibleFlag }; \ |
| DEFINE_C2STRUCT_NO_BASE(name) |
| |
| /// \ingroup internal |
| /// Describe a structure of a templated structure. |
| #define DESCRIBE_TEMPLATED_C2STRUCT(strukt, list) \ |
| template<> \ |
| const std::initializer_list<const C2FieldDescriptor> strukt::fieldList = list; |
| |
| /// \deprecated |
| /// Describe the fields of a structure using an initializer list. |
| #define DESCRIBE_C2STRUCT(name, list) \ |
| const std::initializer_list<const C2FieldDescriptor> C2##name##Struct::fieldList = list; |
| |
| /** |
| * Describe a field of a structure. |
| * These must be in order. |
| * |
| * There are two ways to use this macro: |
| * |
| * ~~~~~~~~~~~~~ (.cpp) |
| * struct C2VideoWidthStruct { |
| * int32_t mWidth; |
| * C2VideoWidthStruct() {} // optional default constructor |
| * C2VideoWidthStruct(int32_t _width) : mWidth(_width) {} |
| * |
| * DEFINE_AND_DESCRIBE_C2STRUCT(VideoWidth) |
| * C2FIELD(mWidth, "width") |
| * }; |
| * ~~~~~~~~~~~~~ |
| * |
| * ~~~~~~~~~~~~~ (.cpp) |
| * struct C2VideoWidthStruct { |
| * int32_t mWidth; |
| * C2VideoWidthStruct() = default; // optional default constructor |
| * C2VideoWidthStruct(int32_t _width) : mWidth(_width) {} |
| * |
| * DEFINE_C2STRUCT(VideoWidth) |
| * } C2_PACK; |
| * |
| * DESCRIBE_C2STRUCT(VideoWidth, { |
| * C2FIELD(mWidth, "width") |
| * }) |
| * ~~~~~~~~~~~~~ |
| * |
| * For flexible structures (those ending in T[]), use the flexible macros: |
| * |
| * ~~~~~~~~~~~~~ (.cpp) |
| * struct C2VideoFlexWidthsStruct { |
| * int32_t mWidths[]; |
| * C2VideoFlexWidthsStruct(); // must have a default constructor |
| * |
| * private: |
| * // may have private constructors taking number of widths as the first argument |
| * // This is used by the C2Param factory methods, e.g. |
| * // C2VideoFlexWidthsGlobalParam::alloc_unique(size_t, int32_t); |
| * C2VideoFlexWidthsStruct(size_t flexCount, int32_t value) { |
| * for (size_t i = 0; i < flexCount; ++i) { |
| * mWidths[i] = value; |
| * } |
| * } |
| * |
| * // If the last argument is T[N] or std::initializer_list<T>, the flexCount will |
| * // be automatically calculated and passed by the C2Param factory methods, e.g. |
| * // int widths[] = { 1, 2, 3 }; |
| * // C2VideoFlexWidthsGlobalParam::alloc_unique(widths); |
| * template<unsigned N> |
| * C2VideoFlexWidthsStruct(size_t flexCount, const int32_t(&init)[N]) { |
| * for (size_t i = 0; i < flexCount; ++i) { |
| * mWidths[i] = init[i]; |
| * } |
| * } |
| * |
| * DEFINE_AND_DESCRIBE_FLEX_C2STRUCT(VideoFlexWidths, mWidths) |
| * C2FIELD(mWidths, "widths") |
| * }; |
| * ~~~~~~~~~~~~~ |
| * |
| * ~~~~~~~~~~~~~ (.cpp) |
| * struct C2VideoFlexWidthsStruct { |
| * int32_t mWidths[]; |
| * C2VideoFlexWidthsStruct(); // must have a default constructor |
| * |
| * DEFINE_FLEX_C2STRUCT(VideoFlexWidths, mWidths) |
| * } C2_PACK; |
| * |
| * DESCRIBE_C2STRUCT(VideoFlexWidths, { |
| * C2FIELD(mWidths, "widths") |
| * }) |
| * ~~~~~~~~~~~~~ |
| * |
| */ |
| #define C2FIELD(member, name) \ |
| C2FieldDescriptor(&((_type*)(nullptr))->member, name), |
| |
| /// \deprecated |
| #define C2SOLE_FIELD(member, name) \ |
| C2FieldDescriptor(&_type::member, name, 0) |
| |
| /// Define a structure with matching baseIndex and start describing its fields. |
| /// This must be at the end of the structure definition. |
| #define DEFINE_AND_DESCRIBE_C2STRUCT(name) \ |
| DEFINE_C2STRUCT(name) } C2_PACK; \ |
| const std::initializer_list<const C2FieldDescriptor> C2##name##Struct::fieldList = { |
| |
| /// Define a flexible structure with matching baseIndex and start describing its fields. |
| /// This must be at the end of the structure definition. |
| #define DEFINE_AND_DESCRIBE_FLEX_C2STRUCT(name, flexMember) \ |
| DEFINE_FLEX_C2STRUCT(name, flexMember) } C2_PACK; \ |
| const std::initializer_list<const C2FieldDescriptor> C2##name##Struct::fieldList = { |
| |
| /** |
| * Parameter reflector class. |
| * |
| * This class centralizes the description of parameter structures. This can be shared |
| * by multiple components as describing a parameter does not imply support of that |
| * parameter. However, each supported parameter and any dependent structures within |
| * must be described by the parameter reflector provided by a component. |
| */ |
| class C2ParamReflector { |
| public: |
| /** |
| * Describes a parameter structure. |
| * |
| * \param[in] paramIndex the base index of the parameter structure |
| * |
| * \return the description of the parameter structure |
| * \retval nullptr if the parameter is not supported by this reflector |
| * |
| * This methods shall not block and return immediately. |
| * |
| * \note this class does not take a set of indices because we would then prefer |
| * to also return any dependent structures, and we don't want this logic to be |
| * repeated in each reflector. Alternately, this could just return a map of all |
| * descriptions, but we want to conserve memory if client only wants the description |
| * of a few indices. |
| */ |
| virtual std::unique_ptr<C2StructDescriptor> describe(C2Param::BaseIndex paramIndex) = 0; |
| |
| protected: |
| virtual ~C2ParamReflector() = default; |
| }; |
| |
| /** |
| * A useable supported values for a field. |
| * |
| * This can be either a range or a set of values. The range can be linear or geometric with a |
| * clear minimum and maximum value, and can have an optional step size or geometric ratio. Values |
| * can optionally represent flags. |
| * |
| * \note Do not use flags to represent bitfields. Use individual values or separate fields instead. |
| */ |
| template<typename T> |
| struct C2TypedFieldSupportedValues { |
| //public: |
| enum Type { |
| RANGE, ///< a numeric range that can be continuous or discrete |
| VALUES, ///< a list of values |
| FLAGS ///< a list of flags that can be OR-ed |
| }; |
| |
| Type type; |
| |
| struct { |
| T min; |
| T max; |
| T step; |
| T nom; |
| T denom; |
| } range; |
| std::vector<T> values; |
| |
| C2TypedFieldSupportedValues(T min, T max, T step = T(std::is_floating_point<T>::value ? 0 : 1)) |
| : type(RANGE), |
| range{min, max, step, (T)1, (T)1} { } |
| |
| C2TypedFieldSupportedValues(T min, T max, T nom, T den) : |
| type(RANGE), |
| range{min, max, (T)0, nom, den} { } |
| |
| C2TypedFieldSupportedValues(bool flags, std::initializer_list<T> list) : |
| type(flags ? FLAGS : VALUES), |
| values(list) {} |
| }; |
| |
| /** |
| * Generic supported values for a field. |
| * |
| * This can be either a range or a set of values. The range can be linear or geometric with a |
| * clear minimum and maximum value, and can have an optional step size or geometric ratio. Values |
| * can optionally represent flags. |
| * |
| * \note Do not use flags to represent bitfields. Use individual values or separate fields instead. |
| */ |
| struct C2FieldSupportedValues { |
| //public: |
| enum Type { |
| RANGE, ///< a numeric range that can be continuous or discrete |
| VALUES, ///< a list of values |
| FLAGS ///< a list of flags that can be OR-ed |
| }; |
| |
| Type type; |
| |
| typedef C2Value::Primitive Primitive; |
| |
| struct { |
| Primitive min; |
| Primitive max; |
| Primitive step; |
| Primitive nom; |
| Primitive denom; |
| } range; |
| std::vector<Primitive> values; |
| |
| template<typename T> |
| C2FieldSupportedValues(T min, T max, T step = T(std::is_floating_point<T>::value ? 0 : 1)) |
| : type(RANGE), |
| range{min, max, step, (T)1, (T)1} { } |
| |
| template<typename T> |
| C2FieldSupportedValues(T min, T max, T nom, T den) : |
| type(RANGE), |
| range{min, max, (T)0, nom, den} { } |
| |
| template<typename T> |
| C2FieldSupportedValues(bool flags, std::initializer_list<T> list) |
| : type(flags ? FLAGS : VALUES), |
| range{(T)0, (T)0, (T)0, (T)0, (T)0} { |
| for(T value : list) { |
| values.emplace_back(value); |
| } |
| } |
| |
| template<typename T, typename E=decltype(C2FieldDescriptor::namedValuesFor(*(T*)0))> |
| C2FieldSupportedValues(bool flags, const T*) |
| : type(flags ? FLAGS : VALUES), |
| range{(T)0, (T)0, (T)0, (T)0, (T)0} { |
| C2FieldDescriptor::named_values_type named = C2FieldDescriptor::namedValuesFor(*(T*)0); |
| for (const C2FieldDescriptor::named_value_type &item : named) { |
| values.emplace_back(item.second); |
| } |
| } |
| }; |
| |
| /// @} |
| |
| } // namespace android |
| |
| #endif // C2PARAM_H_ |
