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.
14 GST_PAD_TEMPLATE_FACTORY (fakesrc_src_factory,
23 GstStaticPadTemplate fakesrc_src_template = GST_STATIC_PAD_TEMPLATE (
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.
37 Not every pad template can be converted to a GstStaticPadTemplate,
38 particularly those which create caps from another source at runtime,
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)
58 GST_STATIC_CAPS2 ( "audio/x-raw-int, "
59 "endianness = (int) " G_STRINGIFY (G_BYTE_ORDER) ", "
60 "signed = (boolean) true, "
63 "rate = (int) [ 8000, 48000 ], "
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().
71 Note that the old caps name is no longer used.
75 caps = GST_CAPS_NEW ("videotestsrc_filter",
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));
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);
94 Not everything can be converted in this way, especially lists and
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.
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.
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.
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.
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 detemined at compile time, but
134 might be actually computed at run-time from other information.
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.
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.
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.
168 Checklist for getcaps:
170 - The getcaps function prototype no longer has the caps parameter.
173 - The returned caps is owned by the caller. Make sure you don't
174 keep a pointer to the caps.
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,
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.
184 Checklist for pad_link:
186 - The pad link function prototypes uses a const GstCaps *.
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 properties in the caps
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
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.
204 - the return value GST_PAD_LINK_REFUSED should be used when the caps
205 are unacceptable for whatever reason.
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
213 - the pad_link function must not call gst_caps_try_set_caps() on
214 the pad that was specified as a parameter.
216 - the pad_link function may (and often should) call
217 gst_caps_try_set_caps() on pads that are not specified as the
220 Checklist for fixate:
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.
226 - The user_data parameter is mainly used for user-provided fixate
227 function. It should be ignored in element fixate functions.