design: collect ideas for having lazy caps

Design doc for having on the fly evaluated caps (see bug #618853).

diff --git a/docs/random/ensonic/lazycaps.txt b/docs/random/ensonic/lazycaps.txt
new file mode 100644 (file)
index 0000000..b631472
--- /dev/null
+++ b/docs/random/ensonic/lazycaps.txt
@@ -0,0 +1,70 @@
+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
+- 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.
+
+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 stucture 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