1 /* GStreamer 2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu> 3 * 2005 Wim Taymans <wim@fluendo.com> 4 * 5 * This library is free software; you can redistribute it and/or 6 * modify it under the terms of the GNU Library General Public 7 * License as published by the Free Software Foundation; either 8 * version 2 of the License, or (at your option) any later version. 9 * 10 * This library is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 * Library General Public License for more details. 14 * 15 * You should have received a copy of the GNU Library General Public 16 * License along with this library; if not, write to the 17 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, 18 * Boston, MA 02110-1301, USA. 19 */ 20 21 #ifndef __GST_BASE_TRANSFORM_H__ 22 #define __GST_BASE_TRANSFORM_H__ 23 24 #include <gst/gst.h> 25 #include <gst/base/base-prelude.h> 26 27 G_BEGIN_DECLS 28 29 #define GST_TYPE_BASE_TRANSFORM (gst_base_transform_get_type()) 30 #define GST_BASE_TRANSFORM(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_BASE_TRANSFORM,GstBaseTransform)) 31 #define GST_BASE_TRANSFORM_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_BASE_TRANSFORM,GstBaseTransformClass)) 32 #define GST_BASE_TRANSFORM_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj),GST_TYPE_BASE_TRANSFORM,GstBaseTransformClass)) 33 #define GST_IS_BASE_TRANSFORM(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_BASE_TRANSFORM)) 34 #define GST_IS_BASE_TRANSFORM_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_BASE_TRANSFORM)) 35 #define GST_BASE_TRANSFORM_CAST(obj) ((GstBaseTransform *)(obj)) 36 37 /** 38 * GST_BASE_TRANSFORM_SINK_NAME: 39 * 40 * The name of the templates for the sink pad. 41 */ 42 #define GST_BASE_TRANSFORM_SINK_NAME "sink" 43 /** 44 * GST_BASE_TRANSFORM_SRC_NAME: 45 * 46 * The name of the templates for the source pad. 47 */ 48 #define GST_BASE_TRANSFORM_SRC_NAME "src" 49 50 /** 51 * GST_BASE_TRANSFORM_SRC_PAD: 52 * @obj: base transform instance 53 * 54 * Gives the pointer to the source #GstPad object of the element. 55 */ 56 #define GST_BASE_TRANSFORM_SRC_PAD(obj) (GST_BASE_TRANSFORM_CAST (obj)->srcpad) 57 58 /** 59 * GST_BASE_TRANSFORM_SINK_PAD: 60 * @obj: base transform instance 61 * 62 * Gives the pointer to the sink #GstPad object of the element. 63 */ 64 #define GST_BASE_TRANSFORM_SINK_PAD(obj) (GST_BASE_TRANSFORM_CAST (obj)->sinkpad) 65 66 /** 67 * GST_BASE_TRANSFORM_FLOW_DROPPED: 68 * 69 * A #GstFlowReturn that can be returned from transform and transform_ip to 70 * indicate that no output buffer was generated. 71 */ 72 #define GST_BASE_TRANSFORM_FLOW_DROPPED GST_FLOW_CUSTOM_SUCCESS 73 74 typedef struct _GstBaseTransform GstBaseTransform; 75 typedef struct _GstBaseTransformClass GstBaseTransformClass; 76 typedef struct _GstBaseTransformPrivate GstBaseTransformPrivate; 77 78 /** 79 * GstBaseTransform: 80 * 81 * The opaque #GstBaseTransform data structure. 82 */ 83 struct _GstBaseTransform { 84 GstElement element; 85 86 /*< protected >*/ 87 /* source and sink pads */ 88 GstPad *sinkpad; 89 GstPad *srcpad; 90 91 /* MT-protected (with STREAM_LOCK) */ 92 gboolean have_segment; 93 GstSegment segment; 94 /* Default submit_input_buffer places the buffer here, 95 * for consumption by the generate_output method: */ 96 GstBuffer *queued_buf; 97 98 /*< private >*/ 99 GstBaseTransformPrivate *priv; 100 101 gpointer _gst_reserved[GST_PADDING_LARGE-1]; 102 }; 103 104 /** 105 * GstBaseTransformClass: 106 * @parent_class: Element parent class 107 * @passthrough_on_same_caps: If set to %TRUE, passthrough mode will be 108 * automatically enabled if the caps are the same. 109 * Set to %FALSE by default. 110 * @transform_ip_on_passthrough: If set to %TRUE, @transform_ip will be called in 111 * passthrough mode. The passed buffer might not be 112 * writable. When %FALSE, neither @transform nor 113 * @transform_ip will be called in passthrough mode. 114 * Set to %TRUE by default. 115 * @transform_caps: Optional. Given the pad in this direction and the given 116 * caps, what caps are allowed on the other pad in this 117 * element ? 118 * @fixate_caps: Optional. Given the pad in this direction and the given 119 * caps, fixate the caps on the other pad. The function takes 120 * ownership of @othercaps and returns a fixated version of 121 * @othercaps. @othercaps is not guaranteed to be writable. 122 * @accept_caps: Optional. 123 * Subclasses can override this method to check if @caps can be 124 * handled by the element. The default implementation might not be 125 * the most optimal way to check this in all cases. 126 * @set_caps: Allows the subclass to be notified of the actual caps set. 127 * @query: Optional. 128 * Handle a requested query. Subclasses that implement this 129 * must chain up to the parent if they didn't handle the 130 * query 131 * @decide_allocation: Setup the allocation parameters for allocating output 132 * buffers. The passed in query contains the result of the 133 * downstream allocation query. This function is only called 134 * when not operating in passthrough mode. The default 135 * implementation will remove all memory dependent metadata. 136 * If there is a @filter_meta method implementation, it will 137 * be called for all metadata API in the downstream query, 138 * otherwise the metadata API is removed. 139 * @filter_meta: Return %TRUE if the metadata API should be proposed in the 140 * upstream allocation query. The default implementation is %NULL 141 * and will cause all metadata to be removed. 142 * @propose_allocation: Propose buffer allocation parameters for upstream elements. 143 * This function must be implemented if the element reads or 144 * writes the buffer content. The query that was passed to 145 * the decide_allocation is passed in this method (or %NULL 146 * when the element is in passthrough mode). The default 147 * implementation will pass the query downstream when in 148 * passthrough mode and will copy all the filtered metadata 149 * API in non-passthrough mode. 150 * @transform_size: Optional. Given the size of a buffer in the given direction 151 * with the given caps, calculate the size in bytes of a buffer 152 * on the other pad with the given other caps. 153 * The default implementation uses get_unit_size and keeps 154 * the number of units the same. 155 * @get_unit_size: Required if the transform is not in-place. 156 * Get the size in bytes of one unit for the given caps. 157 * @start: Optional. 158 * Called when the element starts processing. 159 * Allows opening external resources. 160 * @stop: Optional. 161 * Called when the element stops processing. 162 * Allows closing external resources. 163 * @sink_event: Optional. 164 * Event handler on the sink pad. The default implementation 165 * handles the event and forwards it downstream. 166 * @src_event: Optional. 167 * Event handler on the source pad. The default implementation 168 * handles the event and forwards it upstream. 169 * @prepare_output_buffer: Optional. 170 * Subclasses can override this to do their own 171 * allocation of output buffers. Elements that only do 172 * analysis can return a subbuffer or even just 173 * return a reference to the input buffer (if in 174 * passthrough mode). The default implementation will 175 * use the negotiated allocator or bufferpool and 176 * transform_size to allocate an output buffer or it 177 * will return the input buffer in passthrough mode. 178 * @copy_metadata: Optional. 179 * Copy the metadata from the input buffer to the output buffer. 180 * The default implementation will copy the flags, timestamps and 181 * offsets of the buffer. 182 * @transform_meta: Optional. Transform the metadata on the input buffer to the 183 * output buffer. By default this method copies all meta without 184 * tags. Subclasses can implement this method and return %TRUE if 185 * the metadata is to be copied. 186 * @before_transform: Optional. 187 * This method is called right before the base class will 188 * start processing. Dynamic properties or other delayed 189 * configuration could be performed in this method. 190 * @transform: Required if the element does not operate in-place. 191 * Transforms one incoming buffer to one outgoing buffer. 192 * The function is allowed to change size/timestamp/duration 193 * of the outgoing buffer. 194 * @transform_ip: Required if the element operates in-place. 195 * Transform the incoming buffer in-place. 196 * @submit_input_buffer: Function which accepts a new input buffer and pre-processes it. 197 * The default implementation performs caps (re)negotiation, then 198 * QoS if needed, and places the input buffer into the @queued_buf 199 * member variable. If the buffer is dropped due to QoS, it returns 200 * GST_BASE_TRANSFORM_FLOW_DROPPED. If this input buffer is not 201 * contiguous with any previous input buffer, then @is_discont 202 * is set to %TRUE. (Since: 1.6) 203 * @generate_output: Called after each new input buffer is submitted repeatedly 204 * until it either generates an error or fails to generate an output 205 * buffer. The default implementation takes the contents of the 206 * @queued_buf variable, generates an output buffer if needed 207 * by calling the class @prepare_output_buffer, and then 208 * calls either @transform or @transform_ip. Elements that don't 209 * do 1-to-1 transformations of input to output buffers can either 210 * return GST_BASE_TRANSFORM_FLOW_DROPPED or simply not generate 211 * an output buffer until they are ready to do so. (Since: 1.6) 212 * 213 * Subclasses can override any of the available virtual methods or not, as 214 * needed. At minimum either @transform or @transform_ip need to be overridden. 215 * If the element can overwrite the input data with the results (data is of the 216 * same type and quantity) it should provide @transform_ip. 217 */ 218 struct _GstBaseTransformClass { 219 GstElementClass parent_class; 220 221 /*< public >*/ 222 gboolean passthrough_on_same_caps; 223 gboolean transform_ip_on_passthrough; 224 225 /* virtual methods for subclasses */ 226 GstCaps* (*transform_caps) (GstBaseTransform *trans, 227 GstPadDirection direction, 228 GstCaps *caps, GstCaps *filter); 229 /** 230 * GstBaseTransformClass::fixate_caps: 231 * @othercaps: (transfer full): 232 */ 233 GstCaps* (*fixate_caps) (GstBaseTransform *trans, 234 GstPadDirection direction, GstCaps *caps, 235 GstCaps *othercaps); 236 gboolean (*accept_caps) (GstBaseTransform *trans, GstPadDirection direction, 237 GstCaps *caps); 238 gboolean (*set_caps) (GstBaseTransform *trans, GstCaps *incaps, 239 GstCaps *outcaps); 240 gboolean (*query) (GstBaseTransform *trans, GstPadDirection direction, 241 GstQuery *query); 242 243 /* decide allocation query for output buffers */ 244 gboolean (*decide_allocation) (GstBaseTransform *trans, GstQuery *query); 245 gboolean (*filter_meta) (GstBaseTransform *trans, GstQuery *query, 246 GType api, const GstStructure *params); 247 248 /* propose allocation query parameters for input buffers */ 249 gboolean (*propose_allocation) (GstBaseTransform *trans, GstQuery *decide_query, 250 GstQuery *query); 251 252 /** 253 * GstBaseTransformClass::transform_size: 254 * @othersize: (out): 255 */ 256 gboolean (*transform_size) (GstBaseTransform *trans, 257 GstPadDirection direction, 258 GstCaps *caps, gsize size, 259 GstCaps *othercaps, gsize *othersize); 260 261 /** 262 * GstBaseTransformClass::get_unit_size: 263 * @size: (out): 264 */ 265 gboolean (*get_unit_size) (GstBaseTransform *trans, GstCaps *caps, 266 gsize *size); 267 268 /* states */ 269 gboolean (*start) (GstBaseTransform *trans); 270 gboolean (*stop) (GstBaseTransform *trans); 271 272 /* sink and src pad event handlers */ 273 /** 274 * GstBaseTransformClass::sink_event: 275 * @event: (transfer full): 276 */ 277 gboolean (*sink_event) (GstBaseTransform *trans, GstEvent *event); 278 /** 279 * GstBaseTransformClass::src_event: 280 * @event: (transfer full): 281 */ 282 gboolean (*src_event) (GstBaseTransform *trans, GstEvent *event); 283 284 /** 285 * GstBaseTransformClass::prepare_output_buffer: 286 * @outbuf: (out): 287 */ 288 GstFlowReturn (*prepare_output_buffer) (GstBaseTransform * trans, 289 GstBuffer *input, GstBuffer **outbuf); 290 291 /* metadata */ 292 gboolean (*copy_metadata) (GstBaseTransform *trans, GstBuffer *input, 293 GstBuffer *outbuf); 294 gboolean (*transform_meta) (GstBaseTransform *trans, GstBuffer *outbuf, 295 GstMeta *meta, GstBuffer *inbuf); 296 297 void (*before_transform) (GstBaseTransform *trans, GstBuffer *buffer); 298 299 /* transform */ 300 GstFlowReturn (*transform) (GstBaseTransform *trans, GstBuffer *inbuf, 301 GstBuffer *outbuf); 302 GstFlowReturn (*transform_ip) (GstBaseTransform *trans, GstBuffer *buf); 303 304 GstFlowReturn (*submit_input_buffer) (GstBaseTransform *trans, gboolean is_discont, GstBuffer *input); 305 306 /** 307 * GstBaseTransformClass::generate_output: 308 * @outbuf: (out): 309 */ 310 GstFlowReturn (*generate_output) (GstBaseTransform *trans, GstBuffer **outbuf); 311 312 /*< private >*/ 313 gpointer _gst_reserved[GST_PADDING_LARGE - 2]; 314 }; 315 316 GST_BASE_API 317 GType gst_base_transform_get_type (void); 318 319 GST_BASE_API 320 void gst_base_transform_set_passthrough (GstBaseTransform *trans, 321 gboolean passthrough); 322 GST_BASE_API 323 gboolean gst_base_transform_is_passthrough (GstBaseTransform *trans); 324 325 GST_BASE_API 326 void gst_base_transform_set_in_place (GstBaseTransform *trans, 327 gboolean in_place); 328 GST_BASE_API 329 gboolean gst_base_transform_is_in_place (GstBaseTransform *trans); 330 331 GST_BASE_API 332 void gst_base_transform_update_qos (GstBaseTransform *trans, 333 gdouble proportion, 334 GstClockTimeDiff diff, 335 GstClockTime timestamp); 336 GST_BASE_API 337 void gst_base_transform_set_qos_enabled (GstBaseTransform *trans, 338 gboolean enabled); 339 GST_BASE_API 340 gboolean gst_base_transform_is_qos_enabled (GstBaseTransform *trans); 341 342 GST_BASE_API 343 void gst_base_transform_set_gap_aware (GstBaseTransform *trans, 344 gboolean gap_aware); 345 GST_BASE_API 346 void gst_base_transform_set_prefer_passthrough (GstBaseTransform *trans, 347 gboolean prefer_passthrough); 348 GST_BASE_API 349 GstBufferPool * gst_base_transform_get_buffer_pool (GstBaseTransform *trans); 350 351 GST_BASE_API 352 void gst_base_transform_get_allocator (GstBaseTransform *trans, 353 GstAllocator **allocator, 354 GstAllocationParams *params); 355 GST_BASE_API 356 void gst_base_transform_reconfigure_sink (GstBaseTransform *trans); 357 358 GST_BASE_API 359 void gst_base_transform_reconfigure_src (GstBaseTransform *trans); 360 361 GST_BASE_API 362 gboolean gst_base_transform_update_src_caps (GstBaseTransform *trans, 363 GstCaps *updated_caps); 364 365 GST_BASE_API 366 gboolean gst_base_transform_reconfigure (GstBaseTransform * trans); 367 368 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstBaseTransform, gst_object_unref) 369 370 G_END_DECLS 371 372 #endif /* __GST_BASE_TRANSFORM_H__ */ 373