gstreamer/docs/random/ensonic/lazycaps.txt

Lazy Caps
=========

The idea is to have caps where we evaluate the structures as needed. We can have
these variants of lazy caps:

- construction (e.g. from_string)
  - need user_data (the string/string-array)
  - need a free_func for the user_data
  - need a get_structure_func to fill structure slots as needed
  - we can more easily make this iterator based too
- operations (e.g. intersect) (see [1]).
  - need user_data (the iterator)
  - need a free_func for the user_data
  - need a get_structure_func to fill structure slots as needed

We should add PERFORMANCE category logging to methods that cause lazy caps to be
fully evaluated. To get maximum speed benefit we need to inspect places that 
loop over structures of a caps and turn them into while() loops where possible.

We can use GST_CAPS_FLAGS_LAZY to indicate that caps are not fully constructed.
Once caps are fully evaluated, we can remove the flag (and call the free_func).

Lazy caps might need a lock to protect multiple threads requesting a structure
(get_structure_func).

Accessors
---------
guint gst_caps_get_size (const GstCaps *caps);
- needs to fully evaluate the caps if iterator based :/

GstStructure *gst_caps_get_structure (const GstCaps *caps, guint index);- needs to fully evaluate the caps if iterator based :/
- needs to evaluate all entries up to index if iterator based
- needs to only evaluate requested index if e.g. parse based

gchar *gst_caps_to_string (const GstCaps * caps)
- needs to fully evaluate the caps
- it is used in debugging and serialisation

Construction
------------

Manipulation
------------
void gst_caps_append (GstCaps *caps1, GstCaps *caps2);
- use an iterator

void gst_caps_merge (GstCaps *caps1, GstCaps *caps2);
- use an iterator

void gst_caps_append_structure (GstCaps *caps, GstStructure *structure);
void gst_caps_remove_structure (GstCaps *caps, guint idx);
void gst_caps_merge_structure (GstCaps *caps,
- fully evaluate caps?

GstCaps * gst_caps_copy_nth (const GstCaps *caps, guint nth);
- eval structure and copy

void gst_caps_truncate (GstCaps *caps);
- eval first structure as needed and remove GST_CAPS_FLAGS_LAZY + call free_func

void gst_caps_set_value (GstCaps *caps, const char *field, const GValue *value);
void gst_caps_set_simple (GstCaps *caps, const char *field, ...);
void gst_caps_set_simple_valist (GstCaps *caps, const char *field, va_list varargs);
- fully evaluate caps


Operations
----------


[1] https://bugzilla.gnome.org/show_bug.cgi?id=618853