Adding upstream version 0.3.65.upstream/0.3.65upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 530 insertions, 0 deletions

diff --git a/doc/spa-pod.dox b/doc/spa-pod.dox
new file mode 100644
index 0000000..0c88bb7
--- /dev/null
+++ b/doc/spa-pod.dox
@@ -0,0 +1,530 @@
+/** \page page_spa_pod SPA POD
+
+\ref spa_pod (plain old data) is a sort of data container. It is comparable to
+DBus Variant or LV2 Atom.
+
+A POD can express nested structures of objects (with properties), vectors,
+arrays, sequences and various primitives types. All information in the POD
+is laid out sequentially in memory and can be written directly to
+storage or exchanged between processes or threads without additional
+marshalling.
+
+Each POD is made of a 32 bits size followed by a 32 bits type field,
+followed by the POD contents. This makes it possible to skip over unknown
+POD types. The POD start is always aligned to 8 bytes.
+
+POD's can be efficiently constructed and parsed in real-time threads without
+requiring memory allocations.
+
+POD's use the SPA type system for the basic types and containers. See
+the SPA types for more info.
+
+
+# Types
+
+POD's can contain a number of basic SPA types:
+
+- `SPA_TYPE_None`: No value or a NULL pointer.
+- `SPA_TYPE_Bool`: A boolean value.
+- `SPA_TYPE_Id`: An enumerated value.
+- `SPA_TYPE_Int`, `SPA_TYPE_Long`, `SPA_TYPE_Float`, `SPA_TYPE_Double`:
+  various numeral types, 32 and 64 bits.
+- `SPA_TYPE_String`: A string.
+- `SPA_TYPE_Bytes`: A byte array.
+- `SPA_TYPE_Rectangle`: A rectangle with width and height.
+- `SPA_TYPE_Fraction`: A fraction with numerator and denominator.
+- `SPA_TYPE_Bitmap`: An array of bits.
+
+POD's can be grouped together in these container types:
+
+- `SPA_TYPE_Array`: An array of equal sized objects.
+- `SPA_TYPE_Struct`: A collection of types and objects.
+- `SPA_TYPE_Object`: An object with properties.
+- `SPA_TYPE_Sequence`: A timed sequence of POD's.
+
+POD's can also contain some extra types:
+
+- `SPA_TYPE_Pointer`: A typed pointer in memory.
+- `SPA_TYPE_Fd`: A file descriptor.
+- `SPA_TYPE_Choice`: A choice of values.
+- `SPA_TYPE_Pod`: A generic type for the POD itself.
+
+
+# Constructing A POD
+
+A POD is usually constructed with a `struct spa_pod_builder`. The builder
+needs to be initialized with a memory region to write into. It is
+also possible to dynamically grow the memory as needed.
+
+The most common way to construct a POD is on the stack. This does
+not require any memory allocations. The size of the POD can be
+estimated pretty easily and if the buffer is not large enough, an
+appropriate error will be generated.
+
+The code fragment below initializes a POD builder to write into
+the stack allocated buffer.
+
+\code{.c}
+uint8_t buffer[4096];
+struct spa_pod_builder b;
+spa_pod_builder_init(&b, buffer, sizeof(buffer));
+\endcode
+
+Next we need to write some object into the builder. Let's write
+a simple struct with an Int and Float in it. Structs are comparable
+to JSON arrays.
+
+\code{.c}
+struct spa_pod_frame f;
+spa_pod_builder_push_struct(&b, &f);
+\endcode
+
+First we open the struct container, the `struct spa_pod_frame` keeps
+track of the container context. Next we add some values to
+the container like this:
+
+\code{.c}
+spa_pod_builder_int(&b, 5);
+spa_pod_builder_float(&b, 3.1415f);
+\endcode
+
+Then we close the container by popping the frame again:
+
+\code{.c}
+struct spa_pod *pod;
+pod = spa_pod_builder_pop(&b, &f);
+\endcode
+
+`spa_pod_builder_pop()` returns a reference to the object we completed
+on the stack.
+
+## Using varargs Builder
+
+We can also use the following construct to make POD objects:
+
+\code{.c}
+spa_pod_builder_push_struct(&b, &f);
+spa_pod_builder_add(&b,
+	SPA_POD_Int(5),
+	SPA_POD_Float(3.1415f));
+pod = spa_pod_builder_pop(&b, &f);
+\endcode
+
+Or even shorter:
+
+\code{.c}
+pod = spa_pod_builder_add_struct(&b,
+	SPA_POD_Int(5),
+	SPA_POD_Float(3.1415f));
+\endcode
+
+It's not possible to use the varargs builder to make a sequence or
+array, use the normal builder methods for that.
+
+## Making Objects
+
+POD objects are containers for properties and are comparable to JSON
+objects.
+
+Start by pushing an object:
+
+\code{.c}
+spa_pod_builder_push_object(&b, &f, SPA_TYPE_OBJECT_Props, SPA_PARAM_Props);
+\endcode
+
+An object requires an object type (`SPA_TYPE_OBJECT_Props`) and a context
+ID (`SPA_PARAM_Props`). The object type defines the properties that can be
+added to the object and their meaning. The SPA type system allows you to
+make this connection (See the type system).
+
+Next we can push some properties in the object:
+
+\code{.c}
+spa_pod_builder_prop(&b, SPA_PROP_device, 0);
+spa_pod_builder_string(&b, "hw:0");
+spa_pod_builder_prop(&b, SPA_PROP_frequency, 0);
+spa_pod_builder_float(&b, 440.0);
+\endcode
+
+As can be seen, we always need to push a prop (with key and flags)
+and then the associated value. For performance reasons it is a good
+idea to always push (and parse) the object keys in ascending order.
+
+Don't forget to pop the result when the object is finished:
+
+\code{.c}
+pod = spa_pod_builder_pop(&b, &f);
+\endcode
+
+There is a shortcut for making objects:
+
+\code{.c}
+pod = spa_pod_builder_add_object(&b,
+	SPA_TYPE_OBJECT_Props, SPA_PARAM_Props,
+	SPA_PROP_device,    SPA_POD_String("hw:0"),
+	SPA_PROP_frequency, SPA_POD_Float(440.0f));
+\endcode
+
+## Choice Values
+
+It is possible to express ranges or enumerations of possible
+values for properties (and to some extend structs). This is achieved
+with choice values.
+
+Choice values are really just a choice type and an array of choice values
+(of the same type). Depending on the choice type, the array values are
+interpreted in different ways:
+
+- `SPA_CHOICE_None`: No choice, first value is current.
+- `SPA_CHOICE_Range`: Range: default, min, max.
+- `SPA_CHOICE_Step`: Range with step: default, min, max, step.
+- `SPA_CHOICE_Enum`: Enum: default, alternative,...
+- `SPA_CHOICE_Flags`: Bitmask of flags.
+
+Let's illustrate this with a props object that specifies a range of
+possible values for the frequency:
+
+\code{.c}
+struct spa_pod_frame f2;
+
+spa_pod_builder_push_object(&b, &f, SPA_TYPE_OBJECT_Props, SPA_PARAM_Props);
+spa_pod_builder_prop(&b, SPA_PROP_frequency, 0);
+spa_pod_builder_push_choice(&b, &f2, SPA_CHOICE_Range, 0);
+spa_pod_builder_float(&b, 440.0);   //  default
+spa_pod_builder_float(&b, 110.0);   //  min
+spa_pod_builder_float(&b, 880.0);   //  min
+pod = spa_pod_builder_pop(&b, &f2);
+pod = spa_pod_builder_pop(&b, &f);
+\endcode
+
+As you can see, first push the choice as a range, then the values. A range
+choice expects at least three values, the default value, minimum and maximum
+values. There is a shortcut for this as well using varargs:
+
+\code{.c}
+pod = spa_pod_builder_add_object(&b,
+	SPA_TYPE_OBJECT_Props, SPA_PARAM_Props,
+	SPA_PROP_frequency, SPA_POD_CHOICE_RANGE_Float(440.0f, 110.0f, 880.0f));
+\endcode
+
+## Choice Examples
+
+This is a description of a possible `SPA_TYPE_OBJECT_Format` as used when
+enumerating allowed formats (`SPA_PARAM_EnumFormat`) in SPA objects:
+
+\code{.c}
+pod = spa_pod_builder_add_object(&b,
+	SPA_TYPE_OBJECT_Format, SPA_PARAM_EnumFormat,
+	//  specify the media type and subtype
+	SPA_FORMAT_mediaType,      SPA_POD_Id(SPA_MEDIA_TYPE_audio),
+	SPA_FORMAT_mediaSubtype,   SPA_POD_Id(SPA_MEDIA_SUBTYPE_raw),
+	//  audio/raw properties
+	SPA_FORMAT_AUDIO_format,   SPA_POD_CHOICE_ENUM_Id(
+					SPA_AUDIO_FORMAT_S16, //  default
+					SPA_AUDIO_FORMAT_S16, //  alternative1
+					SPA_AUDIO_FORMAT_S32, //  alternative2
+					SPA_AUDIO_FORMAT_f32  //  alternative3
+				   ),
+	SPA_FORMAT_AUDIO_rate,     SPA_POD_CHOICE_RANGE_Int(
+					44100,		//  default
+					8000,		//  min
+					192000		//  max
+				   ),
+	SPA_FORMAT_AUDIO_channels, SPA_POD_Int(2));
+\endcode
+
+## Fixate
+
+We can remove all choice values from the object with the
+`spa_pod_object_fixate()` method. This modifies the pod in-place and sets all
+choice properties to `SPA_CHOICE_None`, forcing the default value as the
+only available value in the choice.
+
+Running fixate on our previous example would result in an object equivalent
+to:
+
+\code{.c}
+pod = spa_pod_builder_add_object(&b,
+	SPA_TYPE_OBJECT_Format, SPA_PARAM_EnumFormat,
+	//  specify the media type and subtype
+	SPA_FORMAT_mediaType,      SPA_POD_Id(SPA_MEDIA_TYPE_audio),
+	SPA_FORMAT_mediaSubtype,   SPA_POD_Id(SPA_MEDIA_SUBTYPE_raw),
+	//  audio/raw properties
+	SPA_FORMAT_AUDIO_format,   SPA_POD_Id(SPA_AUDIO_FORMAT_S16),
+	SPA_FORMAT_AUDIO_rate,     SPA_POD_Int(44100),
+	SPA_FORMAT_AUDIO_channels, SPA_POD_Int(2));
+\endcode
+
+
+# Parsing A POD
+
+Parsing a POD usually consists of:
+
+- Validating if raw bytes + size can contain a valid POD.
+- Inspecting the type of a POD.
+- Looping over the items in an object or struct.
+- Getting data out of POD's.
+
+## Validating Bytes
+
+Use `spa_pod_from_data()` to check if maxsize of bytes in data contain
+a POD at the size bytes starting at offset. This function checks that
+the POD size will fit and not overflow.
+
+\code{.c}
+struct spa_pod *pod;
+pod = spa_pod_from_data(data, maxsize, offset, size);
+\endcode
+
+## Checking The Type Of POD
+
+Use one of `spa_pod_is_bool()`, `spa_pod_is_int()`, etc to check
+for the type of the pod. For simple (non-container) types,
+`spa_pod_get_bool()`, `spa_pod_get_int()` etc can be used to
+extract the value of the pod.
+
+`spa_pod_is_object_type()` can be used to check if the POD contains
+an object of the expected type.
+
+## Struct Fields
+
+To iterate over the fields of a struct use:
+
+\code{.c}
+struct spa_pod *pod, *obj;
+SPA_POD_STRUCT_FOREACH(obj, pod) {
+	printf("field type:%d\n", pod->type);
+}
+\endcode
+
+For parsing structs it is usually much easier to use the parser
+below.
+
+## Object Properties
+
+To iterate over the properties in an object you can do:
+
+\code{.c}
+struct spa_pod_prop *prop;
+struct spa_pod_object *obj = (struct spa_pod_object*)pod;
+SPA_POD_OBJECT_FOREACH(pod, prop) {
+	printf("prop key:%d\n", prop->key);
+}
+\endcode
+
+There is a function to retrieve the property for a certain key
+in the object. If the properties of the object are in ascending
+order, you can start searching from the previous key.
+
+\code{.c}
+struct spa_pod_prop *prop;
+prop = spa_pod_find_prop(obj, NULL, SPA_FORMAT_AUDIO_format);
+  //  .. use first prop
+prop = spa_pod_find_prop(obj, prop, SPA_FORMAT_AUDIO_rate);
+  //  .. use next prop
+\endcode
+
+## Parser
+
+Similar to the builder, there is a parser object as well.
+
+If the fields in a struct are known, it is much easier to use the
+parser. Similarly, if the object type (and thus its keys) are known,
+the parser is easier.
+
+First initialize a `struct spa_pod_parser`:
+
+\code{.c}
+struct spa_pod_parser p;
+spa_pod_parser_pod(&p, obj);
+\endcode
+
+You can then enter containers such as objects or structs with a push
+operation:
+
+\code{.c}
+struct spa_pod_frame f;
+spa_pod_parser_push_struct(&p, &f);
+\endcode
+
+You need to store the context in a `struct spa_pod_frame` to be able
+to exit the container again later.
+
+You can then parse each field. The parser takes care of moving to the
+next field.
+
+\code{.c}
+uint32_t id, val;
+spa_pod_parser_get_id(&p, &id);
+spa_pod_parser_get_int(&p, &val);
+...
+\endcode
+
+And finally exit the container again:
+
+\code{.c}
+spa_pod_parser_pop(&p, &f);
+\endcode
+
+## Parser With Variable Arguments
+
+In most cases, parsing objects is easier with the variable argument
+functions. The parse function look like the mirror image of the builder
+functions.
+
+To parse a struct:
+
+\code{.c}
+spa_pod_parser_get_struct(&p,
+	SPA_POD_Id(&id),
+	SPA_POD_Int(&val));
+\endcode
+
+To parse properties in an object:
+
+\code{.c}
+uint32_t type, subtype, format, rate, channels;
+spa_pod_parser_get_object(&p,
+	SPA_TYPE_OBJECT_Format, SPA_PARAM_EnumFormat,
+	SPA_FORMAT_mediaType,      SPA_POD_Id(&type),
+	SPA_FORMAT_mediaSubtype,   SPA_POD_Id(&subtype),
+	SPA_FORMAT_AUDIO_format,   SPA_POD_Id(&format),
+	SPA_FORMAT_AUDIO_rate,     SPA_POD_Int(&rate),
+	SPA_FORMAT_AUDIO_channels, SPA_POD_Int(&channels));
+\endcode
+
+When parsing objects it is possible to have optional fields. You can
+make a field optional be parsing it with the `SPA_POD_OPT_` prefix
+for the type.
+
+In the next example, the rate and channels fields are optional
+and when they are not present, the variables will not be changed.
+
+\code{.c}
+uint32_t type, subtype, format, rate = 0, channels = 0;
+spa_pod_parser_get_object(&p,
+	SPA_TYPE_OBJECT_Format, SPA_PARAM_EnumFormat,
+	SPA_FORMAT_mediaType,      SPA_POD_Id(&type),
+	SPA_FORMAT_mediaSubtype,   SPA_POD_Id(&subtype),
+	SPA_FORMAT_AUDIO_format,   SPA_POD_Id(&format),
+	SPA_FORMAT_AUDIO_rate,     SPA_POD_OPT_Int(&rate),
+	SPA_FORMAT_AUDIO_channels, SPA_POD_OPT_Int(&channels));
+\endcode
+
+It is not possible to parse a sequence or array with the parser.
+Use the iterator for this.
+
+## Choice Values
+
+The parser will handle choice values as long as they are of type
+`none`. It will then parse the single value from the choice. When
+dealing with other choice values, it's possible to parse the
+property values into a `struct spa_pod` and then inspect the choice
+manually, if needed.
+
+Here is an example of parsing the format values as a POD:
+
+\code{.c}
+uint32_t type, subtype;
+struct spa_pod *format;
+spa_pod_parser_get_object(&p,
+	SPA_TYPE_OBJECT_Format, SPA_PARAM_EnumFormat,
+	SPA_FORMAT_mediaType,      SPA_POD_Id(&type),
+	SPA_FORMAT_mediaSubtype,   SPA_POD_Id(&subtype),
+	SPA_FORMAT_AUDIO_format,   SPA_POD_Pod(&format));
+\endcode
+
+`spa_pod_get_values()` is a useful function. It returns a
+`struct spa_pod*` with and array of values. For normal POD's
+and choice none values, it simply returns the POD and one value.
+For other choice values it returns the choice type and an array
+of values:
+
+\code{.c}
+struct spa_pod *value;
+uint32_t n_vals, choice;
+
+value = spa_pod_get_values(pod, &n_vals, &choice);
+
+switch (choice) {
+case SPA_CHOICE_None:
+        //  one single value
+	break;
+case SPA_CHOICE_Range:
+        // array of values of type of pod, cast to right type
+	// to iterate.
+	uint32_t *v = SPA_POD_BODY(values);
+	if (n_vals < 3)
+		break;
+	printf("default value: %u\n", v[0]);
+	printf("min value: %u\n", v[1]);
+	printf("max value: %u\n", v[2]);
+	break;
+
+	//  ...
+default:
+	break;
+}
+\endcode
+
+
+# Filter
+
+Given two POD objects of the same type (object, struct, ..) one can
+run a filter and generate a new POD that only contains values that
+are compatible with both input POD's.
+
+This is, for example, used to find a compatible format between two ports.
+
+As an example we can run a filter on two simple POD's:
+
+\code{.c}
+pod = spa_pod_builder_add_object(&b,
+	SPA_TYPE_OBJECT_Format, SPA_PARAM_EnumFormat,
+	SPA_FORMAT_mediaType,      SPA_POD_Id(SPA_MEDIA_TYPE_audio),
+	SPA_FORMAT_mediaSubtype,   SPA_POD_Id(SPA_MEDIA_SUBTYPE_raw),
+	SPA_FORMAT_AUDIO_format,   SPA_POD_CHOICE_ENUM_Id(
+					SPA_AUDIO_FORMAT_S16, //  default
+					SPA_AUDIO_FORMAT_S16, //  alternative1
+					SPA_AUDIO_FORMAT_S32, //  alternative2
+					SPA_AUDIO_FORMAT_f32  //  alternative3
+				   ));
+
+filter = spa_pod_builder_add_object(&b,
+	SPA_TYPE_OBJECT_Format, SPA_PARAM_EnumFormat,
+	SPA_FORMAT_mediaType,      SPA_POD_Id(SPA_MEDIA_TYPE_audio),
+	SPA_FORMAT_mediaSubtype,   SPA_POD_Id(SPA_MEDIA_SUBTYPE_raw),
+	SPA_FORMAT_AUDIO_format,   SPA_POD_CHOICE_ENUM_Id(
+					SPA_AUDIO_FORMAT_S16, //  default
+					SPA_AUDIO_FORMAT_S16, //  alternative1
+					SPA_AUDIO_FORMAT_f64  //  alternative2
+				   ));
+
+struct spa_pod *result;
+if (spa_pod_filter(&b, &result, pod, filter) < 0)
+	goto exit_error;
+\endcode
+
+Filter will contain a POD equivalent to:
+
+\code{.c}
+result = spa_pod_builder_add_object(&b,
+	SPA_TYPE_OBJECT_Format, SPA_PARAM_EnumFormat,
+	SPA_FORMAT_mediaType,      SPA_POD_Id(SPA_MEDIA_TYPE_audio),
+	SPA_FORMAT_mediaSubtype,   SPA_POD_Id(SPA_MEDIA_SUBTYPE_raw),
+	SPA_FORMAT_AUDIO_format,   SPA_AUDIO_FORMAT_S16);
+\endcode
+
+# POD Layout
+
+Each POD has a 32 bits size field, followed by a 32 bits type field. The size
+field specifies the size following the type field.
+
+Each POD is aligned to an 8 byte boundary.
+
+
+\addtogroup spa_pod
+
+See: \ref page_spa_pod
+
+*/