docs/random/caps2

   1
   2 The new caps code uses the type name GstCaps2 and the function
   3 names gst_caps2_*().  Before the CAPS branch is merged, there
   4 will be a global change from caps2 to caps.  Since GstCaps is
   5 no longer defined, it no longer compiles, thus highlighting
   6 exactly what needs to be changed in an element.
   7
   8
   9
  10 Pad Templates:
  11
  12 Old style:
  13
  14   GST_PAD_TEMPLATE_FACTORY (fakesrc_src_factory,
  15     "src%d",
  16     GST_PAD_SRC,
  17     GST_PAD_REQUEST,
  18     GST_CAPS_ANY
  19   );
  20
  21 New style:
  22
  23   GstStaticPadTemplate fakesrc_src_template = GST_STATIC_PAD_TEMPLATE (
  24     "src%d",
  25     GST_PAD_SRC,
  26     GST_PAD_REQUEST,
  27     GST_STATIC_CAPS2_ANY
  28   );
  29
  30 The old style defined a function called fakesrc_src_factory(), which,
  31 when called, returns a pad template.  The new style defines a
  32 GstStaticPadTemplate, which can be converted to a GstPadTemplate
  33 by the function gst_static_pad_template_get().  The 4th argument
  34 is also different -- previously it would call the GST_CAPS_NEW()
  35 function.  Now it is a GstStaticCaps.
  36
  37 Not every pad template can be converted to a GstStaticPadTemplate,
  38 particularly those which create caps from another source at runtime,
  39 such as videotestsrc.
  40
  41 Caps:
  42
  43 Old style:
  44
  45   GST_CAPS_NEW (
  46     "sinesrc_src",
  47     "audio/x-raw-int",
  48       "endianness",     GST_PROPS_INT (G_BYTE_ORDER),
  49       "signed",         GST_PROPS_BOOLEAN (TRUE),
  50       "width",          GST_PROPS_INT (16),
  51       "depth",          GST_PROPS_INT (16),
  52       "rate",           GST_PROPS_INT_RANGE (8000, 48000),
  53       "channels",       GST_PROPS_INT (1)
  54   )
  55
  56 New style:
  57
  58   GST_STATIC_CAPS2 ( "audio/x-raw-int, "
  59       "endianness = (int) " G_STRINGIFY (G_BYTE_ORDER) ", "
  60       "signed = (boolean) true, "
  61       "width = (int) 16, "
  62       "depth = (int) 16, "
  63       "rate = (int) [ 8000, 48000 ], "
  64       "channels = (int) 1"
  65   )
  66
  67 The old style calls a function that creates a GstCaps.  The new style
  68 stores a string in a GstStaticCaps2, and this string is converted to
  69 a caps in the function gst_static_caps2_get().
  70
  71 Note that the old caps name is no longer used.
  72
  73 Old style:
  74
  75   caps = GST_CAPS_NEW ("videotestsrc_filter",
  76                        "video/x-raw-rgb",
  77                        "bpp", GST_PROPS_INT(format->bitspp),
  78                        "endianness", GST_PROPS_INT(endianness),
  79                        "depth", GST_PROPS_INT(format->depth),
  80                        "red_mask", GST_PROPS_INT(format->red_mask),
  81                        "green_mask", GST_PROPS_INT(format->green_mask),
  82                        "blue_mask", GST_PROPS_INT(format->blue_mask));
  83
  84 New style:
  85
  86   caps = gst_caps2_new_simple("video/x-raw-rgb",
  87         "bpp", G_TYPE_INT, format->bitspp,
  88         "endianness", G_TYPE_INT, endianness,
  89         "depth", G_TYPE_INT, format->depth,
  90         "red_mask", G_TYPE_INT, format->red_mask,
  91         "green_mask", G_TYPE_INT, format->green_mask,
  92         "blue_mask", G_TYPE_INT, format->blue_mask);
  93
  94 Not everything can be converted in this way, especially lists and
  95 ranges.
  96
  97
  98 IMPLEMENTATION
  99
 100 Pad Capabilities (caps) are mathematical sets that represent all the
 101 possible stream types that a pad can use.  These general sets are
 102 represented by unions of simpler sets known as caps structures.  Each
 103 caps structure has a media type (e.g., "audio/mpeg") and a number of
 104 properties.  Each property has a name and a GValue.  In normal
 105 circumstances, the GValue will have the types int, boolean, string,
 106 fourcc, and double.  Simple sets are constructed by using GValues
 107 that are lists of other GValues, or the special types that represent
 108 int ranges and double ranges.
 109
 110 A "fixed" caps represents exactly one media format.  This means that
 111 the caps is a union of exactly one caps structure, and each property
 112 in the caps structure is a simple type, i.e., no ranges or lists.
 113
 114 There are two special caps values, "ANY" which represents the union
 115 of all stream types, and "EMPTY", which represents the set of no
 116 stream types.  The ANY caps is often used on generic elements that
 117 handle any type of data (e.g., filesrc and filesink).  The EMPTY
 118 caps is the return value of gst_caps_intersect(), when the two
 119 given caps do not intersect.  In many cases, using EMPTY is invalid.
 120
 121
 122 CAPS NEGOTIATION
 123
 124 Elements provide information to the core about what stream formats
 125 they understand in four ways: the caps in the pad templates, the
 126 caps returned by a pad's getcaps function, accepting/denying
 127 a given caps in the pad link function, and a new fixate function.
 128
 129 The pad template caps should be the union of caps a pad supports
 130 in any potential situation.  Simultaneously, these caps should be
 131 as specific as possible, since it is used to decide which elements
 132 to attempt for autoplugging, without having to load the element.
 133 The pad template caps are generally determined at compile time, but
 134 might be actually computed at run-time from other information.
 135
 136 The getcaps() function returns the caps supported by a given pad,
 137 in the context of the element's state, its link to other elements,
 138 and the devices or files it has opened.  These caps must be a
 139 subset of the pad template caps.  In the NULL state with no links,
 140 the getcaps function should ideally return the same caps as the
 141 pad template.  In rare circumstances, an object property can affect
 142 the caps returned by getcaps, but this is discouraged.  For most
 143 filters, the caps returned by getcaps is directly affected by the
 144 allowed caps on other pads.  For demuxers and decoders, the caps
 145 returned by the srcpad's getcaps function is directly related to
 146 the stream data.  Again, getcaps should return the most specific
 147 caps it reasonably can, since this helps with autoplugging.
 148
 149 The pad link function is the last step in negotiating caps.  The
 150 core calls the pad link function with a fixed caps, meaning that
 151 the stream format is precisely defined, with the caps having one
 152 structure, with no fields that are ranges or lists.
 153
 154 There is also a new pad function "fixate", which is used to help
 155 choose a fixed caps from a non-fixed caps.  This is called in
 156 situations where normal negotiation cannot decide on a fixed caps.
 157 You should almost never implement a fixate function, please ask
 158 me if it is appropriate for your case.  Fixate functions are called
 159 iteratively on the pads until a fixed caps is found.  Fixate functions
 160 are called with a const caps, and should return a caps that is a
 161 strict subset of the given caps.  That is, the function should
 162 create a caps that is "more fixed" than previously, but does not
 163 have to return fixed caps.  If the fixate function can't provide
 164 more fixed caps, it should return NULL.
 165
 166
 167
 168 Checklist for getcaps:
 169
 170  - The getcaps function prototype no longer has the caps parameter.
 171    Remove it.
 172
 173  - The returned caps is owned by the caller.  Make sure you don't
 174    keep a pointer to the caps.
 175
 176  - Make sure that the getcaps function can be called safely in each
 177    element state (NULL, READY, PAUSED, PLAYING), and for any element
 178    configuration (properties, links, devices/files opened or not,
 179    error state, etc.)
 180
 181  - Make sure that the returned caps do not depend on the caps that
 182    indicate the stream type that the pad is currently using.
 183
 184 Checklist for pad_link:
 185
 186  - The pad link function prototypes uses a const GstCaps *.
 187
 188  - Pad link functions are called with fixed caps.  There's no need
 189    to check for this.  This means that you can assume that the caps
 190    is not ANY or EMPTY, and that there is exactly one structure in
 191    the caps, and that all the fields in the structure are fixed.
 192
 193  - Pad link functions are called with caps that are a subset of the
 194    most recent return value of the pad's getcaps function.  Generally,
 195    the getcaps function was called immediately prior to calling the
 196    src_link function.  For 0.8, you can assume that nothing has changed
 197    in your element that would cause a change to the return value of
 198    getcaps.
 199
 200  - the return value GST_PAD_LINK_OK should be used when the caps are
 201    acceptable, and you've extracted all the necessary information from
 202    the caps and set the element's internal state appropriately.
 203
 204  - the return value GST_PAD_LINK_REFUSED should be used when the caps
 205    are unacceptable for whatever reason.
 206
 207  - the return value GST_PAD_LINK_DELAYED should be used when the
 208    element is in a state where it can't determine whether the caps
 209    are acceptable or not.  This is often used if the element needs
 210    to open a device or process data before determining acceptable
 211    caps.
 212
 213  - the pad_link function must not call gst_caps_try_set_caps() on
 214    the pad that was specified as a parameter.
 215
 216  - the pad_link function may (and often should) call
 217    gst_caps_try_set_caps() on pads that are not specified as the
 218    pad parameter.
 219
 220 Checklist for fixate:
 221
 222  - Make sure you actually should be using a fixate function.  Fixate
 223    functions are reasonable for non-fixed primary sources, such as
 224    videotestsrc, v4lsrc, and osssrc.
 225
 226  - The user_data parameter is mainly used for user-provided fixate
 227    function.  It should be ignored in element fixate functions.
 228
 229
 230
 231