Move Codec2-related code from hardware/google/av
Test: None
Bug: 112362730
Change-Id: Ie2f8ff431d65c40333f267ab9877d47089adeea4
diff --git a/media/codec2/include/C2Param.h b/media/codec2/include/C2Param.h
new file mode 100644
index 0000000..40be3b3
--- /dev/null
+++ b/media/codec2/include/C2Param.h
@@ -0,0 +1,1673 @@
+/*
+ * 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 <string>
+#include <type_traits>
+#include <utility>
+#include <vector>
+
+/// \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
+ * - some common member field names are reserved as they are defined as methods for all
+ * parameters:
+ * they are: size, type, kind, index and stream
+ *
+ * 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 param 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
+
+/**
+ * Parameter base class.
+ */
+struct C2Param {
+ // param index encompasses the following:
+ //
+ // - kind (setting, tuning, info, struct)
+ // - scope
+ // - direction (global, input, output)
+ // - stream flag
+ // - stream ID (usually 0)
+ // - and the parameter's type (core index)
+ // - flexible parameter flag
+ // - vendor extension flag
+ // - type index (this includes the vendor extension flag)
+ //
+ // layout:
+ //
+ // kind : <------- scope -------> : <----- core index ----->
+ // +------+-----+---+------+--------+----|------+--------------+
+ // | kind | dir | - |stream|streamID|flex|vendor| type index |
+ // +------+-----+---+------+--------+----+------+--------------+
+ // bit: 31..30 29.28 25 24 .. 17 16 15 14 .. 0
+ //
+public:
+ /**
+ * C2Param kinds, usable as bitmaps.
+ */
+ enum kind_t : uint32_t {
+ NONE = 0,
+ STRUCT = (1 << 0),
+ INFO = (1 << 1),
+ SETTING = (1 << 2),
+ TUNING = (1 << 3) | SETTING, // tunings are settings
+ };
+
+ /**
+ * The parameter type index specifies the underlying parameter type of a parameter as
+ * an integer value.
+ *
+ * Parameter types are divided into two groups: platform types and vendor types.
+ *
+ * Platform types are defined by the platform and are common for all implementations.
+ *
+ * Vendor types are defined by each vendors, so they may differ between implementations.
+ * It is recommended that vendor types be the same for all implementations by a specific
+ * vendor.
+ */
+ typedef uint32_t type_index_t;
+ enum : uint32_t {
+ TYPE_INDEX_VENDOR_START = 0x00008000, ///< vendor indices SHALL start after this
+ };
+
+ /**
+ * Core index is the underlying parameter type for a parameter. It is used to describe the
+ * layout of the parameter structure regardless of the component or parameter kind/scope.
+ *
+ * It is used to identify and distinguish global parameters, and also parameters on a given
+ * port or stream. They must be unique for the set of global parameters, as well as for the
+ * set of parameters on each port or each stream, but the same core index can be used for
+ * parameters on different streams or ports, as well as for global parameters and port/stream
+ * parameters.
+ *
+ * Multiple parameter types can share the same layout.
+ *
+ * \note The layout for all parameters with the same core index across all components must
+ * be identical.
+ */
+ struct CoreIndex {
+ //public:
+ enum : uint32_t {
+ IS_FLEX_FLAG = 0x00010000,
+ };
+
+ protected:
+ enum : uint32_t {
+ KIND_MASK = 0xC0000000,
+ KIND_STRUCT = 0x00000000,
+ KIND_TUNING = 0x40000000,
+ KIND_SETTING = 0x80000000,
+ KIND_INFO = 0xC0000000,
+
+ DIR_MASK = 0x30000000,
+ DIR_GLOBAL = 0x20000000,
+ DIR_UNDEFINED = DIR_MASK, // MUST have all bits set
+ DIR_INPUT = 0x00000000,
+ DIR_OUTPUT = 0x10000000,
+
+ IS_STREAM_FLAG = 0x02000000,
+ STREAM_ID_MASK = 0x01FE0000,
+ STREAM_ID_SHIFT = 17,
+ MAX_STREAM_ID = STREAM_ID_MASK >> STREAM_ID_SHIFT,
+ STREAM_MASK = IS_STREAM_FLAG | STREAM_ID_MASK,
+
+ IS_VENDOR_FLAG = 0x00008000,
+ TYPE_INDEX_MASK = 0x0000FFFF,
+ CORE_MASK = TYPE_INDEX_MASK | IS_FLEX_FLAG,
+ };
+
+ public:
+ /// constructor/conversion from uint32_t
+ inline CoreIndex(uint32_t index) : mIndex(index) { }
+
+ // no conversion from uint64_t
+ inline CoreIndex(uint64_t index) = delete;
+
+ /// returns true iff this is a vendor extension parameter
+ inline bool isVendor() const { return mIndex & IS_VENDOR_FLAG; }
+
+ /// returns true iff this is a flexible parameter (with variable size)
+ inline bool isFlexible() const { return mIndex & IS_FLEX_FLAG; }
+
+ /// returns the core index
+ /// This is the combination of the parameter type index and the flexible flag.
+ inline uint32_t coreIndex() const { return mIndex & CORE_MASK; }
+
+ /// returns the parameter type index
+ inline type_index_t typeIndex() const { return mIndex & TYPE_INDEX_MASK; }
+
+ DEFINE_FIELD_AND_MASK_BASED_COMPARISON_OPERATORS(CoreIndex, mIndex, CORE_MASK)
+
+ protected:
+ uint32_t mIndex;
+ };
+
+ /**
+ * Type encompasses the parameter's kind (tuning, setting, info), its scope (whether the
+ * parameter is global, input or output, and whether it is for a stream) and the its base
+ * index (which also determines its layout).
+ */
+ struct Type : public CoreIndex {
+ //public:
+ /// returns true iff this is a global parameter (not for input nor output)
+ inline bool isGlobal() const { return (mIndex & DIR_MASK) == DIR_GLOBAL; }
+ /// returns true iff this is an input or input stream parameter
+ inline bool forInput() const { return (mIndex & DIR_MASK) == DIR_INPUT; }
+ /// returns true iff this is an output or output stream parameter
+ inline bool forOutput() const { return (mIndex & DIR_MASK) == DIR_OUTPUT; }
+
+ /// returns true iff this is a stream parameter
+ inline bool forStream() const { return mIndex & IS_STREAM_FLAG; }
+ /// 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 & (~STREAM_ID_MASK); }
+
+ /// return the kind (struct, info, setting or tuning) of this param
+ inline kind_t kind() const {
+ switch (mIndex & KIND_MASK) {
+ case KIND_STRUCT: return STRUCT;
+ case KIND_INFO: return INFO;
+ case KIND_SETTING: return SETTING;
+ case KIND_TUNING: return TUNING;
+ default: return NONE; // should not happen
+ }
+ }
+
+ /// constructor/conversion from uint32_t
+ inline Type(uint32_t index) : CoreIndex(index) { }
+
+ // no conversion from uint64_t
+ inline Type(uint64_t index) = delete;
+
+ DEFINE_FIELD_AND_MASK_BASED_COMPARISON_OPERATORS(Type, mIndex, ~STREAM_ID_MASK)
+
+ private:
+ friend struct C2Param; // for setPort()
+ friend struct C2Tuning; // for KIND_TUNING
+ friend struct C2Setting; // for KIND_SETTING
+ friend struct C2Info; // for KIND_INFO
+ // for DIR_GLOBAL
+ 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 & ~DIR_MASK) | (output ? DIR_OUTPUT : DIR_INPUT);
+ 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) { }
+
+ /// copy constructor
+ inline Index(const Index &index) = default;
+
+ // 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;
+ }
+
+ /// Returns an index with stream field set to given stream.
+ inline Index withStream(unsigned stream) const {
+ Index ix = mIndex;
+ (void)ix.setStream(stream);
+ return ix;
+ }
+
+ /// sets the port (direction). Returns true iff successful.
+ inline Index withPort(bool output) const {
+ Index ix = mIndex;
+ (void)ix.setPort(output);
+ return ix;
+ }
+
+ DEFINE_FIELD_BASED_COMPARISON_OPERATORS(Index, mIndex)
+
+ 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() < MAX_STREAM_ID : rawStream() == 0)
+ && (mIndex & DIR_MASK) != DIR_UNDEFINED;
+ }
+
+ /// returns the raw stream ID field
+ inline unsigned rawStream() const {
+ return (mIndex & STREAM_ID_MASK) >> STREAM_ID_SHIFT;
+ }
+
+ /// 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 > MAX_STREAM_ID) {
+ stream = MAX_STREAM_ID;
+ }
+ return (stream << STREAM_ID_SHIFT) & STREAM_ID_MASK;
+ }
+
+ inline bool convertToStream(bool output, unsigned stream) {
+ mIndex = (mIndex & ~DIR_MASK) | IS_STREAM_FLAG;
+ (void)setPort(output);
+ return setStream(stream);
+ }
+
+ inline void convertToPort(bool output) {
+ mIndex = (mIndex & ~(DIR_MASK | IS_STREAM_FLAG));
+ (void)setPort(output);
+ }
+
+ inline void convertToGlobal() {
+ mIndex = (mIndex & ~(DIR_MASK | IS_STREAM_FLAG)) | DIR_GLOBAL;
+ }
+
+ /**
+ * 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 & ~STREAM_ID_MASK) | MakeStreamId(stream);
+ return this->stream() < MAX_STREAM_ID;
+ }
+ 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 Type type() const { return _mIndex.type(); }
+
+ /// returns the index of this parameter
+ /// \todo: should we restrict this to C2ParamField?
+ inline uint32_t index() const { return (uint32_t)_mIndex; }
+
+ /// returns the core index of this parameter
+ inline CoreIndex coreIndex() const { return _mIndex.coreIndex(); }
+
+ /// returns the kind of this parameter
+ inline kind_t 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, but really C2Param must also to be a valid param
+ if (len < sizeof(C2Param)) {
+ return nullptr;
+ }
+ // _mSize must match length
+ C2Param *param = (C2Param*)addr;
+ if (param->_mSize != len) {
+ return nullptr;
+ }
+ return param;
+ }
+
+ /// Returns managed clone of |orig| at heap.
+ inline static std::unique_ptr<C2Param> Copy(const C2Param &orig) {
+ if (orig.size() == 0) {
+ return nullptr;
+ }
+ void *mem = ::operator new (orig.size());
+ C2Param *param = new (mem) C2Param(orig.size(), orig._mIndex);
+ param->updateFrom(orig);
+ return std::unique_ptr<C2Param>(param);
+ }
+
+ /// Returns managed clone of |orig| as a stream parameter at heap.
+ inline static std::unique_ptr<C2Param> CopyAsStream(
+ const C2Param &orig, bool output, unsigned stream) {
+ std::unique_ptr<C2Param> copy = Copy(orig);
+ if (copy) {
+ copy->_mIndex.convertToStream(output, stream);
+ }
+ return copy;
+ }
+
+ /// Returns managed clone of |orig| as a port parameter at heap.
+ inline static std::unique_ptr<C2Param> CopyAsPort(const C2Param &orig, bool output) {
+ std::unique_ptr<C2Param> copy = Copy(orig);
+ if (copy) {
+ copy->_mIndex.convertToPort(output);
+ }
+ return copy;
+ }
+
+ /// Returns managed clone of |orig| as a global parameter at heap.
+ inline static std::unique_ptr<C2Param> CopyAsGlobal(const C2Param &orig) {
+ std::unique_ptr<C2Param> copy = Copy(orig);
+ if (copy) {
+ copy->_mIndex.convertToGlobal();
+ }
+ return copy;
+ }
+
+#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, 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::DIR_MASK) ? 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 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 { PARAM_KIND = Type::KIND_SETTING };
+};
+
+/**
+ * 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 { PARAM_KIND = Type::KIND_TUNING };
+};
+
+/**
+ * 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 { PARAM_KIND = Type::KIND_INFO };
+};
+
+/**
+ * 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 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:
+ friend struct _C2ParamInspector;
+ friend struct C2FieldDescriptor;
+
+ uint32_t _mOffset; // offset of field
+ uint32_t _mSize; // size of field
+};
+
+/**
+ * Structure uniquely specifying a 'field' in a configuration. The field
+ * can be a field of a configuration, a subfield of a field of a configuration,
+ * and even the whole configuration. Moreover, if the field can point to an
+ * element in a array field, or to the entire array field.
+ *
+ * This structure is used for querying supported values for a field, as well
+ * as communicating configuration failures and conflicts when trying to change
+ * a configuration for a component/interface or a store.
+ */
+struct C2ParamField {
+//public:
+ /**
+ * Create a field identifier using a configuration parameter (variable),
+ * and a pointer to member.
+ *
+ * ~~~~~~~~~~~~~ (.cpp)
+ *
+ * struct C2SomeParam {
+ * uint32_t mField;
+ * uint32_t mArray[2];
+ * C2OtherStruct mStruct;
+ * uint32_t mFlexArray[];
+ * } *mParam;
+ *
+ * C2ParamField(mParam, &mParam->mField);
+ * C2ParamField(mParam, &mParam->mArray);
+ * C2ParamField(mParam, &mParam->mArray[0]);
+ * C2ParamField(mParam, &mParam->mStruct.mSubField);
+ * C2ParamField(mParam, &mParam->mFlexArray);
+ * C2ParamField(mParam, &mParam->mFlexArray[2]);
+ *
+ * ~~~~~~~~~~~~~
+ *
+ * \todo fix what this is for T[] (for now size becomes T[1])
+ *
+ * \note this does not work for 64-bit members as it triggers a
+ * 'taking address of packed member' warning.
+ *
+ * \param param pointer to parameter
+ * \param offset member pointer
+ */
+ template<typename S, typename T>
+ inline C2ParamField(S* param, T* offset)
+ : _mIndex(param->index()),
+ _mFieldId((T*)((uintptr_t)offset - (uintptr_t)param)) {}
+
+ template<typename S, typename T>
+ inline static C2ParamField Make(S& param, T& offset) {
+ return C2ParamField(param.index(), (uintptr_t)&offset - (uintptr_t)¶m, sizeof(T));
+ }
+
+ /**
+ * Create a field identifier using a configuration parameter (variable),
+ * and a member pointer. This method cannot be used to refer to an
+ * array element or a subfield.
+ *
+ * ~~~~~~~~~~~~~ (.cpp)
+ *
+ * C2SomeParam mParam;
+ * C2ParamField(&mParam, &C2SomeParam::mMemberField);
+ *
+ * ~~~~~~~~~~~~~
+ *
+ * \param p pointer to parameter
+ * \param T member pointer to the field member
+ */
+ template<typename R, typename T, typename U>
+ inline C2ParamField(U *p, R T::* pm) : _mIndex(p->index()), _mFieldId(p, pm) { }
+
+ /**
+ * Create a field identifier to a configuration parameter (variable).
+ *
+ * ~~~~~~~~~~~~~ (.cpp)
+ *
+ * C2SomeParam mParam;
+ * C2ParamField(&mParam);
+ *
+ * ~~~~~~~~~~~~~
+ *
+ * \param param pointer to parameter
+ */
+ template<typename S>
+ inline C2ParamField(S* param)
+ : _mIndex(param->index()), _mFieldId(0u, param->size()) { }
+
+ /** Copy constructor. */
+ inline C2ParamField(const C2ParamField &other) = default;
+
+ /**
+ * Equality operator.
+ */
+ inline bool operator==(const C2ParamField &other) const {
+ return _mIndex == other._mIndex && _mFieldId == other._mFieldId;
+ }
+
+ /**
+ * Ordering operator.
+ */
+ inline bool operator<(const C2ParamField &other) const {
+ return _mIndex < other._mIndex ||
+ (_mIndex == other._mIndex && _mFieldId < other._mFieldId);
+ }
+
+ DEFINE_OTHER_COMPARISON_OPERATORS(C2ParamField)
+
+protected:
+ inline C2ParamField(C2Param::Index index, uint32_t offset, uint32_t size)
+ : _mIndex(index), _mFieldId(offset, size) {}
+
+private:
+ friend struct _C2ParamInspector;
+
+ C2Param::Index _mIndex; ///< parameter index
+ _C2FieldId _mFieldId; ///< field identifier
+};
+
+/**
+ * A shared (union) representation of numeric values
+ */
+class C2Value {
+public:
+ /// A union of supported primitive types.
+ union Primitive {
+ // first member is always zero initialized so it must be the largest
+ uint64_t u64; ///< uint64_t value
+ int64_t i64; ///< int64_t value
+ c2_cntr64_t c64; ///< c2_cntr64_t value
+ uint32_t u32; ///< uint32_t value
+ int32_t i32; ///< int32_t value
+ c2_cntr32_t c32; ///< c2_cntr32_t value
+ float fp; ///< float value
+
+ // constructors - implicit
+ Primitive(uint64_t value) : u64(value) { }
+ Primitive(int64_t value) : i64(value) { }
+ Primitive(c2_cntr64_t value) : c64(value) { }
+ Primitive(uint32_t value) : u32(value) { }
+ Primitive(int32_t value) : i32(value) { }
+ Primitive(c2_cntr32_t value) : c32(value) { }
+ Primitive(uint8_t value) : u32(value) { }
+ Primitive(char value) : i32(value) { }
+ Primitive(float value) : fp(value) { }
+
+ // allow construction from enum type
+ template<typename E, typename = typename std::enable_if<std::is_enum<E>::value>::type>
+ Primitive(E value)
+ : Primitive(static_cast<typename std::underlying_type<E>::type>(value)) { }
+
+ Primitive() : u64(0) { }
+
+ /** gets value out of the union */
+ template<typename T> const T &ref() const;
+
+ // verify that we can assume standard aliasing
+ static_assert(sizeof(u64) == sizeof(i64), "");
+ static_assert(sizeof(u64) == sizeof(c64), "");
+ static_assert(sizeof(u32) == sizeof(i32), "");
+ static_assert(sizeof(u32) == sizeof(c32), "");
+ };
+ // verify that we can assume standard aliasing
+ static_assert(offsetof(Primitive, u64) == offsetof(Primitive, i64), "");
+ static_assert(offsetof(Primitive, u64) == offsetof(Primitive, c64), "");
+ static_assert(offsetof(Primitive, u32) == offsetof(Primitive, i32), "");
+ static_assert(offsetof(Primitive, u32) == offsetof(Primitive, c32), "");
+
+ enum type_t : uint32_t {
+ NO_INIT,
+ INT32,
+ UINT32,
+ CNTR32,
+ INT64,
+ UINT64,
+ CNTR64,
+ FLOAT,
+ };
+
+ template<typename T, bool = std::is_enum<T>::value>
+ inline static constexpr type_t TypeFor() {
+ using U = typename std::underlying_type<T>::type;
+ return TypeFor<U>();
+ }
+
+ // deprectated
+ template<typename T, bool B = std::is_enum<T>::value>
+ inline static constexpr type_t typeFor() {
+ return TypeFor<T, B>();
+ }
+
+ // constructors - implicit
+ template<typename T>
+ C2Value(T value) : _mType(typeFor<T>()), _mValue(value) { }
+
+ C2Value() : _mType(NO_INIT) { }
+
+ inline type_t 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;
+ }
+
+ /// returns the address of the value
+ void *get() const {
+ return _mType == NO_INIT ? nullptr : (void*)&_mValue;
+ }
+
+ /// returns the size of the contained value
+ size_t inline sizeOf() const {
+ return SizeFor(_mType);
+ }
+
+ static size_t SizeFor(type_t type) {
+ switch (type) {
+ case INT32:
+ case UINT32:
+ case CNTR32: return sizeof(_mValue.i32);
+ case INT64:
+ case UINT64:
+ case CNTR64: return sizeof(_mValue.i64);
+ case FLOAT: return sizeof(_mValue.fp);
+ default: return 0;
+ }
+ }
+
+private:
+ type_t _mType;
+ Primitive _mValue;
+};
+
+template<> inline const int32_t &C2Value::Primitive::ref<int32_t>() const { return i32; }
+template<> inline const int64_t &C2Value::Primitive::ref<int64_t>() const { return i64; }
+template<> inline const uint32_t &C2Value::Primitive::ref<uint32_t>() const { return u32; }
+template<> inline const uint64_t &C2Value::Primitive::ref<uint64_t>() const { return u64; }
+template<> inline const c2_cntr32_t &C2Value::Primitive::ref<c2_cntr32_t>() const { return c32; }
+template<> inline const c2_cntr64_t &C2Value::Primitive::ref<c2_cntr64_t>() const { return c64; }
+template<> inline const float &C2Value::Primitive::ref<float>() const { return fp; }
+
+// provide types for enums and uint8_t, char even though we don't provide reading as them
+template<> constexpr C2Value::type_t C2Value::TypeFor<char, false>() { return INT32; }
+template<> constexpr C2Value::type_t C2Value::TypeFor<int32_t, false>() { return INT32; }
+template<> constexpr C2Value::type_t C2Value::TypeFor<int64_t, false>() { return INT64; }
+template<> constexpr C2Value::type_t C2Value::TypeFor<uint8_t, false>() { return UINT32; }
+template<> constexpr C2Value::type_t C2Value::TypeFor<uint32_t, false>() { return UINT32; }
+template<> constexpr C2Value::type_t C2Value::TypeFor<uint64_t, false>() { return UINT64; }
+template<> constexpr C2Value::type_t C2Value::TypeFor<c2_cntr32_t, false>() { return CNTR32; }
+template<> constexpr C2Value::type_t C2Value::TypeFor<c2_cntr64_t, false>() { return CNTR64; }
+template<> constexpr C2Value::type_t C2Value::TypeFor<float, false>() { return FLOAT; }
+
+// forward declare easy enum template
+template<typename E> struct C2EasyEnum;
+
+/**
+ * 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_t : uint32_t {
+ // primitive types
+ INT32 = C2Value::INT32, ///< 32-bit signed integer
+ UINT32 = C2Value::UINT32, ///< 32-bit unsigned integer
+ CNTR32 = C2Value::CNTR32, ///< 32-bit counter
+ INT64 = C2Value::INT64, ///< 64-bit signed integer
+ UINT64 = C2Value::UINT64, ///< 64-bit signed integer
+ CNTR64 = C2Value::CNTR64, ///< 64-bit counter
+ 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 = 0x20000, ///< structs. Marked with this flag in addition to their coreIndex.
+ };
+
+ typedef std::pair<C2String, C2Value::Primitive> NamedValueType;
+ typedef std::vector<NamedValueType> NamedValuesType;
+ //typedef std::pair<std::vector<C2String>, std::vector<C2Value::Primitive>> NamedValuesType;
+
+ /**
+ * 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 NamedValuesType namedValuesFor(const B &);
+
+ /** specialization for easy enums */
+ template<typename E>
+ inline static NamedValuesType namedValuesFor(const C2EasyEnum<E> &) {
+ return namedValuesFor(*(E*)nullptr);
+ }
+
+private:
+ template<typename B, bool enabled=std::is_arithmetic<B>::value || std::is_enum<B>::value>
+ struct C2_HIDE _NamedValuesGetter;
+
+public:
+ inline C2FieldDescriptor(uint32_t type, uint32_t extent, C2String name, size_t offset, size_t size)
+ : _mType((type_t)type), _mExtent(extent), _mName(name), _mFieldId(offset, size) { }
+
+ inline C2FieldDescriptor(const C2FieldDescriptor &) = default;
+
+ template<typename T, class B=typename std::remove_extent<T>::type>
+ inline C2FieldDescriptor(const T* offset, const char *name)
+ : _mType(this->GetType((B*)nullptr)),
+ _mExtent(std::is_array<T>::value ? std::extent<T>::value : 1),
+ _mName(name),
+ _mNamedValues(_NamedValuesGetter<B>::getNamedValues()),
+ _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)),
+ _mExtent(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>
+ inline C2FieldDescriptor(S*, T S::* field, const char *name)
+ : _mType(this->GetType((B*)nullptr)),
+ _mExtent(std::is_array<T>::value ? std::extent<T>::value : 1),
+ _mName(name),
+ _mFieldId(&(((S*)0)->*field)) {}
+
+ /// returns the type of this field
+ inline type_t 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 extent() const { return _mExtent; }
+ /// returns the name of the field
+ inline C2String name() const { return _mName; }
+
+ const NamedValuesType &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:
+ /**
+ * Construct an offseted field descriptor.
+ */
+ inline C2FieldDescriptor(const C2FieldDescriptor &desc, size_t offset)
+ : _mType(desc._mType), _mExtent(desc._mExtent),
+ _mName(desc._mName), _mNamedValues(desc._mNamedValues),
+ _mFieldId(desc._mFieldId._mOffset + offset, desc._mFieldId._mSize) { }
+
+ type_t _mType;
+ uint32_t _mExtent; // 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.
+ C2String _mName;
+ NamedValuesType _mNamedValues;
+
+ _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_t GetType(int32_t*) { return INT32; }
+ inline static type_t GetType(uint32_t*) { return UINT32; }
+ inline static type_t GetType(c2_cntr32_t*) { return CNTR32; }
+ inline static type_t GetType(int64_t*) { return INT64; }
+ inline static type_t GetType(uint64_t*) { return UINT64; }
+ inline static type_t GetType(c2_cntr64_t*) { return CNTR64; }
+ inline static type_t GetType(float*) { return FLOAT; }
+ inline static type_t GetType(char*) { return STRING; }
+ inline static type_t GetType(uint8_t*) { return BLOB; }
+
+ template<typename T,
+ class=typename std::enable_if<std::is_enum<T>::value>::type>
+ inline static type_t GetType(T*) {
+ typename std::underlying_type<T>::type underlying(0);
+ return GetType(&underlying);
+ }
+
+ // verify C2Struct by having a FieldList() and a CORE_INDEX.
+ template<typename T,
+ class=decltype(T::CORE_INDEX + 1), class=decltype(T::FieldList())>
+ inline static type_t GetType(T*) {
+ static_assert(!std::is_base_of<C2Param, T>::value, "cannot use C2Params as fields");
+ return (type_t)(T::CORE_INDEX | STRUCT_FLAG);
+ }
+
+ friend struct _C2ParamInspector;
+};
+
+// no named values for compound types
+template<typename B>
+struct C2FieldDescriptor::_NamedValuesGetter<B, false> {
+ inline static C2FieldDescriptor::NamedValuesType getNamedValues() {
+ return NamedValuesType();
+ }
+};
+
+template<typename B>
+struct C2FieldDescriptor::_NamedValuesGetter<B, true> {
+ inline static C2FieldDescriptor::NamedValuesType getNamedValues() {
+ return C2FieldDescriptor::namedValuesFor(*(B*)nullptr);
+ }
+};
+
+#define DEFINE_NO_NAMED_VALUES_FOR(type) \
+template<> inline C2FieldDescriptor::NamedValuesType C2FieldDescriptor::namedValuesFor(const type &) { \
+ return NamedValuesType(); \
+}
+
+// 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(c2_cntr32_t)
+DEFINE_NO_NAMED_VALUES_FOR(int64_t)
+DEFINE_NO_NAMED_VALUES_FOR(uint64_t)
+DEFINE_NO_NAMED_VALUES_FOR(c2_cntr64_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 core index of the struct
+ inline C2Param::CoreIndex coreIndex() const { return _mType.coreIndex(); }
+
+ // Returns the number of fields in this struct (not counting any recursive fields).
+ // Must be at least 1 for valid structs.
+ inline size_t numFields() const { return _mFields.size(); }
+
+ // Returns the list of direct fields (not counting any recursive fields).
+ typedef std::vector<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 names 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::CORE_INDEX, T::FieldList()) { }
+
+ inline C2StructDescriptor(
+ C2Param::CoreIndex type,
+ const std::vector<C2FieldDescriptor> &fields)
+ : _mType(type), _mFields(fields) { }
+
+private:
+ friend struct _C2ParamInspector;
+
+ inline C2StructDescriptor(
+ C2Param::CoreIndex type,
+ std::vector<C2FieldDescriptor> &&fields)
+ : _mType(type), _mFields(std::move(fields)) { }
+
+ const C2Param::CoreIndex _mType;
+ const std::vector<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 _mAttrib & IS_REQUIRED; }
+
+ /**
+ * 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 _mAttrib & IS_PERSISTENT; }
+
+ inline bool isStrict() const { return _mAttrib & IS_STRICT; }
+
+ inline bool isReadOnly() const { return _mAttrib & IS_READ_ONLY; }
+
+ inline bool isVisible() const { return !(_mAttrib & IS_HIDDEN); }
+
+ inline bool isPublic() const { return !(_mAttrib & IS_INTERNAL); }
+
+ /// 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 index
+ inline C2Param::Index index() const { return _mIndex; }
+
+ /// Returns the indices of parameters that this parameter has a dependency on
+ inline const std::vector<C2Param::Index> &dependencies() const { return _mDependencies; }
+
+ /// \deprecated
+ template<typename T>
+ inline C2ParamDescriptor(bool isRequired, C2StringLiteral name, const T*)
+ : _mIndex(T::PARAM_TYPE),
+ _mAttrib(IS_PERSISTENT | (isRequired ? IS_REQUIRED : 0)),
+ _mName(name) { }
+
+ /// \deprecated
+ inline C2ParamDescriptor(
+ bool isRequired, C2StringLiteral name, C2Param::Index index)
+ : _mIndex(index),
+ _mAttrib(IS_PERSISTENT | (isRequired ? IS_REQUIRED : 0)),
+ _mName(name) { }
+
+ enum attrib_t : uint32_t {
+ // flags that default on
+ IS_REQUIRED = 1u << 0, ///< parameter is required to be specified
+ IS_PERSISTENT = 1u << 1, ///< parameter retains its value
+ // flags that default off
+ IS_STRICT = 1u << 2, ///< parameter is strict
+ IS_READ_ONLY = 1u << 3, ///< parameter is publicly read-only
+ IS_HIDDEN = 1u << 4, ///< parameter shall not be visible to clients
+ IS_INTERNAL = 1u << 5, ///< parameter shall not be used by framework (other than testing)
+ IS_CONST = 1u << 6 | IS_READ_ONLY, ///< parameter is publicly const (hence read-only)
+ };
+
+ inline C2ParamDescriptor(
+ C2Param::Index index, attrib_t attrib, C2StringLiteral name)
+ : _mIndex(index),
+ _mAttrib(attrib),
+ _mName(name) { }
+
+ inline C2ParamDescriptor(
+ C2Param::Index index, attrib_t attrib, C2String &&name,
+ std::vector<C2Param::Index> &&dependencies)
+ : _mIndex(index),
+ _mAttrib(attrib),
+ _mName(name),
+ _mDependencies(std::move(dependencies)) { }
+
+private:
+ const C2Param::Index _mIndex;
+ const uint32_t _mAttrib;
+ const C2String _mName;
+ std::vector<C2Param::Index> _mDependencies;
+
+ friend struct _C2ParamInspector;
+};
+
+DEFINE_ENUM_OPERATORS(::C2ParamDescriptor::attrib_t)
+
+
+/// \ingroup internal
+/// Define a structure without CORE_INDEX.
+/// \note _FIELD_LIST is used only during declaration so that C2Struct declarations can end with
+/// a simple list of C2FIELD-s and closing bracket. Mark it unused as it is not used in templated
+/// structs.
+#define DEFINE_BASE_C2STRUCT(name) \
+private: \
+ const static std::vector<C2FieldDescriptor> _FIELD_LIST __unused; /**< structure fields */ \
+public: \
+ typedef C2##name##Struct _type; /**< type name shorthand */ \
+ static const std::vector<C2FieldDescriptor> FieldList(); /**< structure fields factory */
+
+/// Define a structure with matching CORE_INDEX.
+#define DEFINE_C2STRUCT(name) \
+public: \
+ enum : uint32_t { CORE_INDEX = kParamIndex##name }; \
+ DEFINE_BASE_C2STRUCT(name)
+
+/// Define a flexible structure without CORE_INDEX.
+#define DEFINE_BASE_FLEX_C2STRUCT(name, flexMember) \
+public: \
+ FLEX(C2##name##Struct, flexMember) \
+ DEFINE_BASE_C2STRUCT(name)
+
+/// Define a flexible structure with matching CORE_INDEX.
+#define DEFINE_FLEX_C2STRUCT(name, flexMember) \
+public: \
+ FLEX(C2##name##Struct, flexMember) \
+ enum : uint32_t { CORE_INDEX = kParamIndex##name | C2Param::CoreIndex::IS_FLEX_FLAG }; \
+ DEFINE_BASE_C2STRUCT(name)
+
+/// \ingroup internal
+/// Describe a structure of a templated structure.
+// Use list... as the argument gets resubsitituted and it contains commas. Alternative would be
+// to wrap list in an expression, e.g. ({ std::vector<C2FieldDescriptor> list; })) which converts
+// it from an initializer list to a vector.
+#define DESCRIBE_TEMPLATED_C2STRUCT(strukt, list...) \
+ _DESCRIBE_TEMPLATABLE_C2STRUCT(template<>, strukt, __C2_GENERATE_GLOBAL_VARS__, list)
+
+/// \deprecated
+/// Describe the fields of a structure using an initializer list.
+#define DESCRIBE_C2STRUCT(name, list...) \
+ _DESCRIBE_TEMPLATABLE_C2STRUCT(, C2##name##Struct, __C2_GENERATE_GLOBAL_VARS__, list)
+
+/// \ingroup internal
+/// Macro layer to get value of enabled that is passed in as a macro variable
+#define _DESCRIBE_TEMPLATABLE_C2STRUCT(template, strukt, enabled, list...) \
+ __DESCRIBE_TEMPLATABLE_C2STRUCT(template, strukt, enabled, list)
+
+/// \ingroup internal
+/// Macro layer to resolve to the specific macro based on macro variable
+#define __DESCRIBE_TEMPLATABLE_C2STRUCT(template, strukt, enabled, list...) \
+ ___DESCRIBE_TEMPLATABLE_C2STRUCT##enabled(template, strukt, list)
+
+#define ___DESCRIBE_TEMPLATABLE_C2STRUCT(template, strukt, list...) \
+ template \
+ const std::vector<C2FieldDescriptor> strukt::FieldList() { return list; }
+
+#define ___DESCRIBE_TEMPLATABLE_C2STRUCT__C2_GENERATE_GLOBAL_VARS__(template, strukt, 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 width;
+ * C2VideoWidthStruct() {} // optional default constructor
+ * C2VideoWidthStruct(int32_t _width) : width(_width) {}
+ *
+ * DEFINE_AND_DESCRIBE_C2STRUCT(VideoWidth)
+ * C2FIELD(width, "width")
+ * };
+ * ~~~~~~~~~~~~~
+ *
+ * ~~~~~~~~~~~~~ (.cpp)
+ * struct C2VideoWidthStruct {
+ * int32_t width;
+ * C2VideoWidthStruct() = default; // optional default constructor
+ * C2VideoWidthStruct(int32_t _width) : width(_width) {}
+ *
+ * DEFINE_C2STRUCT(VideoWidth)
+ * } C2_PACK;
+ *
+ * DESCRIBE_C2STRUCT(VideoWidth, {
+ * C2FIELD(width, "width")
+ * })
+ * ~~~~~~~~~~~~~
+ *
+ * For flexible structures (those ending in T[]), use the flexible macros:
+ *
+ * ~~~~~~~~~~~~~ (.cpp)
+ * struct C2VideoFlexWidthsStruct {
+ * int32_t widths[];
+ * 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::AllocUnique(size_t, int32_t);
+ * C2VideoFlexWidthsStruct(size_t flexCount, int32_t value) {
+ * for (size_t i = 0; i < flexCount; ++i) {
+ * widths[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::AllocUnique(widths);
+ * template<unsigned N>
+ * C2VideoFlexWidthsStruct(size_t flexCount, const int32_t(&init)[N]) {
+ * for (size_t i = 0; i < flexCount; ++i) {
+ * widths[i] = init[i];
+ * }
+ * }
+ *
+ * DEFINE_AND_DESCRIBE_FLEX_C2STRUCT(VideoFlexWidths, widths)
+ * C2FIELD(widths, "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 DESCRIBE_C2FIELD(member, name) \
+ C2FieldDescriptor(&((_type*)(nullptr))->member, name),
+
+#define C2FIELD(member, name) _C2FIELD(member, name, __C2_GENERATE_GLOBAL_VARS__)
+/// \if 0
+#define _C2FIELD(member, name, enabled) __C2FIELD(member, name, enabled)
+#define __C2FIELD(member, name, enabled) DESCRIBE_C2FIELD##enabled(member, name)
+#define DESCRIBE_C2FIELD__C2_GENERATE_GLOBAL_VARS__(member, name)
+/// \endif
+
+/// Define a structure with matching CORE_INDEX and start describing its fields.
+/// This must be at the end of the structure definition.
+#define DEFINE_AND_DESCRIBE_C2STRUCT(name) \
+ _DEFINE_AND_DESCRIBE_C2STRUCT(name, DEFINE_C2STRUCT, __C2_GENERATE_GLOBAL_VARS__)
+
+/// Define a base structure (with no CORE_INDEX) and start describing its fields.
+/// This must be at the end of the structure definition.
+#define DEFINE_AND_DESCRIBE_BASE_C2STRUCT(name) \
+ _DEFINE_AND_DESCRIBE_C2STRUCT(name, DEFINE_BASE_C2STRUCT, __C2_GENERATE_GLOBAL_VARS__)
+
+/// Define a flexible structure with matching CORE_INDEX and start describing its fields.
+/// This must be at the end of the structure definition.
+#define DEFINE_AND_DESCRIBE_FLEX_C2STRUCT(name, flexMember) \
+ _DEFINE_AND_DESCRIBE_FLEX_C2STRUCT( \
+ name, flexMember, DEFINE_FLEX_C2STRUCT, __C2_GENERATE_GLOBAL_VARS__)
+
+/// Define a flexible base structure (with no CORE_INDEX) and start describing its fields.
+/// This must be at the end of the structure definition.
+#define DEFINE_AND_DESCRIBE_BASE_FLEX_C2STRUCT(name, flexMember) \
+ _DEFINE_AND_DESCRIBE_FLEX_C2STRUCT( \
+ name, flexMember, DEFINE_BASE_FLEX_C2STRUCT, __C2_GENERATE_GLOBAL_VARS__)
+
+/// \if 0
+/*
+ Alternate declaration of field definitions in case no field list is to be generated.
+ The specific macro is chosed based on the value of __C2_GENERATE_GLOBAL_VARS__ (whether it is
+ defined (to be empty) or not. This requires two level of macro substitution.
+ TRICKY: use namespace declaration to handle closing bracket that is normally after
+ these macros.
+*/
+
+#define _DEFINE_AND_DESCRIBE_C2STRUCT(name, defineMacro, enabled) \
+ __DEFINE_AND_DESCRIBE_C2STRUCT(name, defineMacro, enabled)
+#define __DEFINE_AND_DESCRIBE_C2STRUCT(name, defineMacro, enabled) \
+ ___DEFINE_AND_DESCRIBE_C2STRUCT##enabled(name, defineMacro)
+#define ___DEFINE_AND_DESCRIBE_C2STRUCT__C2_GENERATE_GLOBAL_VARS__(name, defineMacro) \
+ defineMacro(name) } C2_PACK; namespace {
+#define ___DEFINE_AND_DESCRIBE_C2STRUCT(name, defineMacro) \
+ defineMacro(name) } C2_PACK; \
+ const std::vector<C2FieldDescriptor> C2##name##Struct::FieldList() { return _FIELD_LIST; } \
+ const std::vector<C2FieldDescriptor> C2##name##Struct::_FIELD_LIST = {
+
+#define _DEFINE_AND_DESCRIBE_FLEX_C2STRUCT(name, flexMember, defineMacro, enabled) \
+ __DEFINE_AND_DESCRIBE_FLEX_C2STRUCT(name, flexMember, defineMacro, enabled)
+#define __DEFINE_AND_DESCRIBE_FLEX_C2STRUCT(name, flexMember, defineMacro, enabled) \
+ ___DEFINE_AND_DESCRIBE_FLEX_C2STRUCT##enabled(name, flexMember, defineMacro)
+#define ___DEFINE_AND_DESCRIBE_FLEX_C2STRUCT__C2_GENERATE_GLOBAL_VARS__(name, flexMember, defineMacro) \
+ defineMacro(name, flexMember) } C2_PACK; namespace {
+#define ___DEFINE_AND_DESCRIBE_FLEX_C2STRUCT(name, flexMember, defineMacro) \
+ defineMacro(name, flexMember) } C2_PACK; \
+ const std::vector<C2FieldDescriptor> C2##name##Struct::FieldList() { return _FIELD_LIST; } \
+ const std::vector<C2FieldDescriptor> C2##name##Struct::_FIELD_LIST = {
+/// \endif
+
+
+/**
+ * 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] coreIndex the core index of the parameter structure containing at least the
+ * core index
+ *
+ * \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::CoreIndex coreIndex) const = 0;
+
+protected:
+ virtual ~C2ParamReflector() = default;
+};
+
+/**
+ * Generic supported values for a field.
+ *
+ * This can be either a range or a set of values. The range can be a simple range, an arithmetic,
+ * geometric or multiply-accumulate series with a clear minimum and maximum value. Values can
+ * be discrete values, or can optionally represent flags to be or-ed.
+ *
+ * \note Do not use flags to represent bitfields. Use individual values or separate fields instead.
+ */
+struct C2FieldSupportedValues {
+//public:
+ enum type_t {
+ EMPTY, ///< no supported values
+ 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_t type; /** Type of values for this field. */
+
+ typedef C2Value::Primitive Primitive;
+
+ /**
+ * Range specifier for supported value. Used if type is RANGE.
+ *
+ * If step is 0 and num and denom are both 1, the supported values are any value, for which
+ * min <= value <= max.
+ *
+ * Otherwise, the range represents a geometric/arithmetic/multiply-accumulate series, where
+ * successive supported values can be derived from previous values (starting at min), using the
+ * following formula:
+ * v[0] = min
+ * v[i] = v[i-1] * num / denom + step for i >= 1, while min < v[i] <= max.
+ */
+ struct {
+ /** Lower end of the range (inclusive). */
+ Primitive min;
+ /** Upper end of the range (inclusive if permitted by series). */
+ Primitive max;
+ /** Step between supported values. */
+ Primitive step;
+ /** Numerator of a geometric series. */
+ Primitive num;
+ /** Denominator of a geometric series. */
+ Primitive denom;
+ } range;
+
+ /**
+ * List of values. Used if type is VALUES or FLAGS.
+ *
+ * If type is VALUES, this is the list of supported values in decreasing preference.
+ *
+ * If type is FLAGS, this vector contains { min-mask, flag1, flag2... }. Basically, the first
+ * value is the required set of flags to be set, and the rest of the values are flags that can
+ * be set independently. FLAGS is only supported for integral types. Supported flags should
+ * not overlap, as it can make validation non-deterministic. The standard validation method
+ * is that starting from the original value, if each flag is removed when fully present (the
+ * min-mask must be fully present), we shall arrive at 0.
+ */
+ std::vector<Primitive> values;
+
+ C2FieldSupportedValues()
+ : type(EMPTY) {
+ }
+
+ 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 num, T den) :
+ type(RANGE),
+ range{min, max, (T)0, num, den} { }
+
+ template<typename T>
+ C2FieldSupportedValues(T min, T max, T step, T num, T den)
+ : type(RANGE),
+ range{min, max, step, num, den} { }
+
+ /// \deprecated
+ 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);
+ }
+ }
+
+ /// \deprecated
+ template<typename T>
+ C2FieldSupportedValues(bool flags, const std::vector<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);
+ }
+ }
+
+ /// \internal
+ /// \todo: create separate values vs. flags initializer as for flags we want
+ /// to list both allowed and required flags
+ 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::NamedValuesType named = C2FieldDescriptor::namedValuesFor(*(T*)0);
+ if (flags) {
+ values.emplace_back(0); // min-mask defaults to 0
+ }
+ for (const C2FieldDescriptor::NamedValueType &item : named){
+ values.emplace_back(item.second);
+ }
+ }
+};
+
+/**
+ * Supported values for a specific field.
+ *
+ * This is a pair of the field specifier together with an optional supported values object.
+ * This structure is used when reporting parameter configuration failures and conflicts.
+ */
+struct C2ParamFieldValues {
+ C2ParamField paramOrField; ///< the field or parameter
+ /// optional supported values for the field if paramOrField specifies an actual field that is
+ /// numeric (non struct, blob or string). Supported values for arrays (including string and
+ /// blobs) describe the supported values for each element (character for string, and bytes for
+ /// blobs). It is optional for read-only strings and blobs.
+ std::unique_ptr<C2FieldSupportedValues> values;
+
+ // This struct is meant to be move constructed.
+ C2_DEFAULT_MOVE(C2ParamFieldValues);
+
+ // Copy constructor/assignment is also provided as this object may get copied.
+ C2ParamFieldValues(const C2ParamFieldValues &other)
+ : paramOrField(other.paramOrField),
+ values(other.values ? std::make_unique<C2FieldSupportedValues>(*other.values) : nullptr) { }
+
+ C2ParamFieldValues& operator=(const C2ParamFieldValues &other) {
+ paramOrField = other.paramOrField;
+ values = other.values ? std::make_unique<C2FieldSupportedValues>(*other.values) : nullptr;
+ return *this;
+ }
+
+
+ /**
+ * Construct with no values.
+ */
+ C2ParamFieldValues(const C2ParamField ¶mOrField_)
+ : paramOrField(paramOrField_) { }
+
+ /**
+ * Construct with values.
+ */
+ C2ParamFieldValues(const C2ParamField ¶mOrField_, const C2FieldSupportedValues &values_)
+ : paramOrField(paramOrField_),
+ values(std::make_unique<C2FieldSupportedValues>(values_)) { }
+
+ /**
+ * Construct from fields.
+ */
+ C2ParamFieldValues(const C2ParamField ¶mOrField_, std::unique_ptr<C2FieldSupportedValues> &&values_)
+ : paramOrField(paramOrField_),
+ values(std::move(values_)) { }
+};
+
+/// @}
+
+// include debug header for C2Params.h if C2Debug.h was already included
+#ifdef C2UTILS_DEBUG_H_
+#include <util/C2Debug-param.h>
+#endif
+
+#endif // C2PARAM_H_