diff --git a/ChangeLog b/ChangeLog index 527f3e099c..e70bcc8c43 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,11 @@ +2006-05-03 Thomas Vander Stichele + + * docs/libs/gstreamer-libs-sections.txt: + make sure GstBaseTransformClass shows up in the docs + * libs/gst/base/gstbasetransform.c: + * libs/gst/base/gstbasetransform.h: + move docs so gtk-doc picks it up now + 2006-05-02 Stefan Kost * docs/libs/gstreamer-libs-sections.txt: diff --git a/docs/libs/gstreamer-libs-sections.txt b/docs/libs/gstreamer-libs-sections.txt index 06f36ce911..3ec14549ca 100644 --- a/docs/libs/gstreamer-libs-sections.txt +++ b/docs/libs/gstreamer-libs-sections.txt @@ -187,6 +187,7 @@ gst_base_sink_get_type GstBaseTransform gst/base/gstbasetransform.h GstBaseTransform +GstBaseTransformClass gst_base_transform_is_passthrough gst_base_transform_set_passthrough @@ -202,7 +203,6 @@ GST_BASE_TRANSFORM_SINK_PAD GST_BASE_TRANSFORM_SRC_PAD -GstBaseTransformClass GST_BASE_TRANSFORM GST_IS_BASE_TRANSFORM GST_TYPE_BASE_TRANSFORM diff --git a/libs/gst/base/gstbasetransform.c b/libs/gst/base/gstbasetransform.c index a7fd7ad106..7f4d1add6f 100644 --- a/libs/gst/base/gstbasetransform.c +++ b/libs/gst/base/gstbasetransform.c @@ -60,18 +60,22 @@ * element negotiates the same caps on both pads. * * - * passthrough_on_same_caps on an element that doesn't implement a transform_caps - * function is useful for elements that only inspect data (such as level) + * passthrough_on_same_caps on an element that doesn't implement a + * transform_caps function is useful for elements that only inspect data + * (such as level) * * * * Example elements * Level - * Videoscale, audioconvert, ffmpegcolorspace, audioresample in certain modes. + * Videoscale, audioconvert, ffmpegcolorspace, audioresample in + * certain modes. * * * - * Modifications in-place - input buffer and output buffer are the same thing. + * + * Modifications in-place - input buffer and output buffer are the + * same thing. * * The element must implement a transform_ip function. * @@ -79,41 +83,46 @@ * Output buffer size must <= input buffer size * * - * If the always_in_place flag is set, non-writable buffers will be copied and - * passed to the transform_ip function, otherwise a new buffer will be created - * and the transform function called. + * If the always_in_place flag is set, non-writable buffers will be copied + * and passed to the transform_ip function, otherwise a new buffer will be + * created and the transform function called. * * - * Incoming writable buffers will be passed to the transform_ip function immediately. - * + * Incoming writable buffers will be passed to the transform_ip function + * immediately. * - * only implementing transform_ip and not transform implies always_in_place = - * TRUE + * only implementing transform_ip and not transform implies always_in_place + * = TRUE * * * * Example elements * Volume - * Audioconvert in certain modes (signed/unsigned conversion) - * ffmpegcolorspace in certain modes (endianness swapping) + * Audioconvert in certain modes (signed/unsigned + * conversion) + * ffmpegcolorspace in certain modes (endianness + * swapping) * * * - * Modifications only to the caps/metadata of a buffer + * + * Modifications only to the caps/metadata of a buffer * - * The element does not require writable data, but non-writable buffers should - * be subbuffered so that the meta-information can be replaced. + * The element does not require writable data, but non-writable buffers + * should be subbuffered so that the meta-information can be replaced. * * * Elements wishing to operate in this mode should replace the - * prepare_output_buffer method to create subbuffers of the input buffer and - * set always_in_place to TRUE + * prepare_output_buffer method to create subbuffers of the input buffer + * and set always_in_place to TRUE * * * * Example elements - * Capsfilter when setting caps on outgoing buffers that have none. - * identity when it is going to re-timestamp buffers by datarate. + * Capsfilter when setting caps on outgoing buffers that have + * none. + * identity when it is going to re-timestamp buffers by + * datarate. * * * @@ -130,14 +139,15 @@ * * * Example elements - * Videoscale, ffmpegcolorspace, audioconvert when doing scaling/conversions + * Videoscale, ffmpegcolorspace, audioconvert when doing + * scaling/conversions * * * * Special output buffer allocations * - * Elements which need to do special allocation of their output buffers other - * than what gst_buffer_pad_alloc allows should implement a + * Elements which need to do special allocation of their output buffers + * other than what gst_buffer_pad_alloc allows should implement a * prepare_output_buffer method, which calls the parent implementation and * passes the newly allocated buffer. * @@ -157,8 +167,8 @@ * interested in modifying the buffers. * * - * Elements which are always in passthrough mode whenever the same caps has - * been negotiated on both pads can set the class variable + * Elements which are always in passthrough mode whenever the same caps + * has been negotiated on both pads can set the class variable * passthrough_on_same_caps to have this behaviour automatically. * * diff --git a/libs/gst/base/gstbasetransform.h b/libs/gst/base/gstbasetransform.h index d2be43d479..9d9b15602f 100644 --- a/libs/gst/base/gstbasetransform.h +++ b/libs/gst/base/gstbasetransform.h @@ -50,7 +50,7 @@ G_BEGIN_DECLS /** * GST_BASE_TRANSFORM_SRC_PAD: * @obj: base transform instance - * + * * Gives the pointer to the source #GstPad object of the element. * * Since: 0.10.4 @@ -60,7 +60,7 @@ G_BEGIN_DECLS /** * GST_BASE_TRANSFORM_SINK_PAD: * @obj: base transform instance - * + * * Gives the pointer to the sink #GstPad object of the element. * * Since: 0.10.4 @@ -114,12 +114,44 @@ struct _GstBaseTransform { }; /** - * GstBaseTransformClass::transform_caps: - * @direction: the pad direction - * @caps: the caps - * - * This method should answer the question "given this pad, and given these - * caps, what caps would you allow on the other pad inside your element ?" + * GstBaseTransformClass: + * @transform_caps: Optional. given the pad in this direction and the given + * caps, what caps are allowed on the other pad in this + * element ? + * @fixate_caps: Optional. Given the pad in this direction and the given + * caps, fixate the caps on the other pad. + * @transform_size: Optional. given the size of a buffer in the given direction + * with the given caps, calculate the size in bytes of a buffer + * on the other pad with the given other caps. + * The default implementation uses get_unit_size and keeps + * the number of units the same. + * @get_unit_size: Required if the transform is not in-place. + * get the size in bytes of one unit for the given caps. + * @set_caps: allows the subclass to be notified of the actual caps set. + * @start: Optional. + * Called when the element starts processing. + * Allows opening external resources. + * @stop: Optional. + * Called when the element stops processing. + * Allows closing external resources. + * @transform: Required if the element does not operate in-place. + * Transforms one incoming buffer to one outgoing buffer. + * The function is allowed to change size/timestamp/duration + * of the outgoing buffer. + * @transform_ip: Required if the element operates in-place. + * Transform the incoming buffer in-place. + * @event: Optional. + * Event handler on the sink pad. + * @src_event: Optional. + * Event handler on the source pad. + * @passthrough_on_same_caps: If set to TRUE, passthrough mode will be + * automatically enabled if the caps are the same. + * @prepare_output_buffer: Optional. + * Subclasses can override this to do their own + * allocation of output buffers. Elements that only do + * analysis can return a subbuffer or even just + * increment the reference to the input buffer (if in + * passthrough mode) */ struct _GstBaseTransformClass { GstElementClass parent_class; @@ -127,60 +159,37 @@ struct _GstBaseTransformClass { /*< public >*/ /* virtual methods for subclasses */ - /* given the (non-)fixed simple caps on the pad in the given direction, - * what can I do on the other pad ? */ GstCaps* (*transform_caps) (GstBaseTransform *trans, GstPadDirection direction, GstCaps *caps); - /* given caps on one pad, how would you fixate caps on the other pad ? */ void (*fixate_caps) (GstBaseTransform *trans, GstPadDirection direction, GstCaps *caps, GstCaps *othercaps); - /* given the size of a buffer in the given direction with the given caps, - * calculate the byte size of an buffer on the other side with the given - * other caps; the default - * implementation uses get_size and keeps the number of units the same */ gboolean (*transform_size) (GstBaseTransform *trans, GstPadDirection direction, GstCaps *caps, guint size, GstCaps *othercaps, guint *othersize); - /* get the byte size of one unit for a given caps. - * Always needs to be implemented if the transform is not in-place. */ gboolean (*get_unit_size) (GstBaseTransform *trans, GstCaps *caps, guint *size); - /* notify the subclass of new caps */ gboolean (*set_caps) (GstBaseTransform *trans, GstCaps *incaps, GstCaps *outcaps); - /* start and stop processing, ideal for opening/closing the resource */ gboolean (*start) (GstBaseTransform *trans); gboolean (*stop) (GstBaseTransform *trans); - /* sink event */ gboolean (*event) (GstBaseTransform *trans, GstEvent *event); - /* transform one incoming buffer to one outgoing buffer. - * Always needs to be implemented unless always operating in-place. - * transform function is allowed to change size/timestamp/duration of - * the outgoing buffer. */ GstFlowReturn (*transform) (GstBaseTransform *trans, GstBuffer *inbuf, GstBuffer *outbuf); - - /* transform a buffer inplace */ GstFlowReturn (*transform_ip) (GstBaseTransform *trans, GstBuffer *buf); /* FIXME: When adjusting the padding, move these to nicer places in the class */ - /* Set by child classes to automatically do passthrough mode */ gboolean passthrough_on_same_caps; - /* Subclasses can override this to do their own allocation of output buffers. - * Elements that only do analysis can return a subbuffer or even just - * increment the reference to the input buffer (if in passthrough mode) - */ GstFlowReturn (*prepare_output_buffer) (GstBaseTransform * trans, GstBuffer *input, gint size, GstCaps *caps, GstBuffer **buf); @@ -201,11 +210,11 @@ void gst_base_transform_set_in_place (GstBaseTransform *trans, gboolean in_place); gboolean gst_base_transform_is_in_place (GstBaseTransform *trans); -void gst_base_transform_update_qos (GstBaseTransform *trans, - gdouble proportion, - GstClockTimeDiff diff, +void gst_base_transform_update_qos (GstBaseTransform *trans, + gdouble proportion, + GstClockTimeDiff diff, GstClockTime timestamp); -void gst_base_transform_set_qos_enabled (GstBaseTransform *trans, +void gst_base_transform_set_qos_enabled (GstBaseTransform *trans, gboolean enabled); gboolean gst_base_transform_is_qos_enabled (GstBaseTransform *trans);