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 * should 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 on 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 GstCaps* (*fixate_caps) (GstBaseTransform *trans, 230 GstPadDirection direction, GstCaps *caps, 231 GstCaps *othercaps); 232 gboolean (*accept_caps) (GstBaseTransform *trans, GstPadDirection direction, 233 GstCaps *caps); 234 gboolean (*set_caps) (GstBaseTransform *trans, GstCaps *incaps, 235 GstCaps *outcaps); 236 gboolean (*query) (GstBaseTransform *trans, GstPadDirection direction, 237 GstQuery *query); 238 239 /* decide allocation query for output buffers */ 240 gboolean (*decide_allocation) (GstBaseTransform *trans, GstQuery *query); 241 gboolean (*filter_meta) (GstBaseTransform *trans, GstQuery *query, 242 GType api, const GstStructure *params); 243 244 /* propose allocation query parameters for input buffers */ 245 gboolean (*propose_allocation) (GstBaseTransform *trans, GstQuery *decide_query, 246 GstQuery *query); 247 248 /** 249 * GstBaseTransformClass::transform_size: 250 * @othersize: (out): 251 */ 252 gboolean (*transform_size) (GstBaseTransform *trans, 253 GstPadDirection direction, 254 GstCaps *caps, gsize size, 255 GstCaps *othercaps, gsize *othersize); 256 257 /** 258 * GstBaseTransformClass::get_unit_size: 259 * @size: (out): 260 */ 261 gboolean (*get_unit_size) (GstBaseTransform *trans, GstCaps *caps, 262 gsize *size); 263 264 /* states */ 265 gboolean (*start) (GstBaseTransform *trans); 266 gboolean (*stop) (GstBaseTransform *trans); 267 268 /* sink and src pad event handlers */ 269 gboolean (*sink_event) (GstBaseTransform *trans, GstEvent *event); 270 gboolean (*src_event) (GstBaseTransform *trans, GstEvent *event); 271 272 /** 273 * GstBaseTransformClass::prepare_output_buffer: 274 * @outbuf: (out): 275 */ 276 GstFlowReturn (*prepare_output_buffer) (GstBaseTransform * trans, 277 GstBuffer *input, GstBuffer **outbuf); 278 279 /* metadata */ 280 gboolean (*copy_metadata) (GstBaseTransform *trans, GstBuffer *input, 281 GstBuffer *outbuf); 282 gboolean (*transform_meta) (GstBaseTransform *trans, GstBuffer *outbuf, 283 GstMeta *meta, GstBuffer *inbuf); 284 285 void (*before_transform) (GstBaseTransform *trans, GstBuffer *buffer); 286 287 /* transform */ 288 GstFlowReturn (*transform) (GstBaseTransform *trans, GstBuffer *inbuf, 289 GstBuffer *outbuf); 290 GstFlowReturn (*transform_ip) (GstBaseTransform *trans, GstBuffer *buf); 291 292 GstFlowReturn (*submit_input_buffer) (GstBaseTransform *trans, gboolean is_discont, GstBuffer *input); 293 294 /** 295 * GstBaseTransformClass::generate_output: 296 * @outbuf: (out): 297 */ 298 GstFlowReturn (*generate_output) (GstBaseTransform *trans, GstBuffer **outbuf); 299 300 /*< private >*/ 301 gpointer _gst_reserved[GST_PADDING_LARGE - 2]; 302 }; 303 304 GST_BASE_API 305 GType gst_base_transform_get_type (void); 306 307 GST_BASE_API 308 void gst_base_transform_set_passthrough (GstBaseTransform *trans, 309 gboolean passthrough); 310 GST_BASE_API 311 gboolean gst_base_transform_is_passthrough (GstBaseTransform *trans); 312 313 GST_BASE_API 314 void gst_base_transform_set_in_place (GstBaseTransform *trans, 315 gboolean in_place); 316 GST_BASE_API 317 gboolean gst_base_transform_is_in_place (GstBaseTransform *trans); 318 319 GST_BASE_API 320 void gst_base_transform_update_qos (GstBaseTransform *trans, 321 gdouble proportion, 322 GstClockTimeDiff diff, 323 GstClockTime timestamp); 324 GST_BASE_API 325 void gst_base_transform_set_qos_enabled (GstBaseTransform *trans, 326 gboolean enabled); 327 GST_BASE_API 328 gboolean gst_base_transform_is_qos_enabled (GstBaseTransform *trans); 329 330 GST_BASE_API 331 void gst_base_transform_set_gap_aware (GstBaseTransform *trans, 332 gboolean gap_aware); 333 GST_BASE_API 334 void gst_base_transform_set_prefer_passthrough (GstBaseTransform *trans, 335 gboolean prefer_passthrough); 336 GST_BASE_API 337 GstBufferPool * gst_base_transform_get_buffer_pool (GstBaseTransform *trans); 338 339 GST_BASE_API 340 void gst_base_transform_get_allocator (GstBaseTransform *trans, 341 GstAllocator **allocator, 342 GstAllocationParams *params); 343 GST_BASE_API 344 void gst_base_transform_reconfigure_sink (GstBaseTransform *trans); 345 346 GST_BASE_API 347 void gst_base_transform_reconfigure_src (GstBaseTransform *trans); 348 349 GST_BASE_API 350 gboolean gst_base_transform_update_src_caps (GstBaseTransform *trans, 351 GstCaps *updated_caps); 352 353 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC 354 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstBaseTransform, gst_object_unref) 355 #endif 356 357 G_END_DECLS 358 359 #endif /* __GST_BASE_TRANSFORM_H__ */ 360