video: Update/add docs

This commit is contained in:
Edward Hervey 2012-03-06 18:49:11 +01:00
parent a1b7f84794
commit 33e8e137a6
7 changed files with 139 additions and 37 deletions

View file

@ -294,6 +294,7 @@ gst_base_video_encoder_get_oldest_frame
gst_base_video_encoder_finish_frame
gst_base_video_encoder_set_latency
gst_base_video_encoder_set_latency_fields
gst_base_video_encoder_set_headers
<SUBSECTION Standard>
GST_BASE_VIDEO_ENCODER
GST_IS_BASE_VIDEO_ENCODER
@ -326,6 +327,7 @@ gst_base_video_decoder_alloc_src_buffer
gst_base_video_decoder_alloc_src_frame
gst_base_video_decoder_get_state
gst_base_video_decoder_get_max_decode_time
gst_base_video_decoder_drop_frame
gst_base_video_decoder_finish_frame
<SUBSECTION Standard>
GST_BASE_VIDEO_DECODER
@ -336,10 +338,17 @@ GST_BASE_VIDEO_DECODER_CLASS
GST_IS_BASE_VIDEO_DECODER_CLASS
GST_BASE_VIDEO_DECODER_GET_CLASS
</SECTION>
yes
<SECTION>
<FILE>gstbasevideocodec</FILE>
<TITLE>GstBaseVideoCodec</TITLE>
GstBaseVideoCodec
GstVideoFrame
gst_video_frame_ref
gst_video_frame_unref
gst_base_video_codec_new_frame
GstVideoState
gst_video_state_get_timestamp
GST_BASE_VIDEO_CODEC_SINK_NAME
GST_BASE_VIDEO_CODEC_SRC_NAME
GST_BASE_VIDEO_CODEC_SRC_PAD
@ -347,13 +356,8 @@ GST_BASE_VIDEO_CODEC_SINK_PAD
GST_BASE_VIDEO_CODEC_FLOW_NEED_DATA
GST_BASE_VIDEO_CODEC_STREAM_LOCK
GST_BASE_VIDEO_CODEC_STREAM_UNLOCK
GstVideoState
GstVideoFrame
GstBaseVideoCodec
GstBaseVideoCodecClass
gst_base_video_codec_new_frame
gst_base_video_codec_free_frame
<SUBSECTION Standard>
GstBaseVideoCodecClass
GST_BASE_VIDEO_CODEC
GST_IS_BASE_VIDEO_CODEC
GST_TYPE_BASE_VIDEO_CODEC
@ -361,6 +365,7 @@ gst_base_video_codec_get_type
GST_BASE_VIDEO_CODEC_CLASS
GST_IS_BASE_VIDEO_CODEC_CLASS
GST_BASE_VIDEO_CODEC_GET_CLASS
gst_video_frame_get_type
</SECTION>
<SECTION>
@ -437,7 +442,6 @@ gst_camerabin_preview_set_caps
<FILE>gstbasevideoutils</FILE>
gst_base_video_rawvideo_convert
gst_base_video_encoded_video_convert
gst_video_state_get_timestamp
</SECTION>
<SECTION>

View file

@ -21,6 +21,12 @@
#include "config.h"
#endif
/**
* SECTION:gstbasevideocodec
* @short_description: Base class for video codecs
* @see_also: #GstBaseVideoDecoder , #GstBaseVideoEncoder
*/
/* FIXME 0.11: suppress warnings for deprecated API such as GStaticRecMutex
* with newer GLib versions (>= 2.31.0) */
#define GLIB_DISABLE_DEPRECATION_WARNINGS
@ -189,6 +195,14 @@ gst_base_video_codec_change_state (GstElement * element,
return ret;
}
/**
* gst_base_video_codec_new_frame:
* @base_video_codec: a #GstBaseVideoCodec
*
* Create a new blank #GstVideoFrame.
*
* Returns: (transfer full): a new #GstVideoFrame
*/
GstVideoFrame *
gst_base_video_codec_new_frame (GstBaseVideoCodec * base_video_codec)
{
@ -231,6 +245,14 @@ _gst_video_frame_free (GstVideoFrame * frame)
g_slice_free (GstVideoFrame, frame);
}
/**
* gst_video_frame_ref:
* @frame: a #GstVideoFrame
*
* Increases the refcount of the given frame by one.
*
* Returns: @buf
*/
GstVideoFrame *
gst_video_frame_ref (GstVideoFrame * frame)
{
@ -241,6 +263,13 @@ gst_video_frame_ref (GstVideoFrame * frame)
return frame;
}
/**
* gst_video_frame_unref:
* @frame: a #GstVideoFrame
*
* Decreases the refcount of the frame. If the refcount reaches 0, the frame
* will be freed.
*/
void
gst_video_frame_unref (GstVideoFrame * frame)
{

View file

@ -76,10 +76,27 @@ G_BEGIN_DECLS
/**
* GST_BASE_VIDEO_CODEC_FLOW_NEED_DATA:
*
* Returned while parsing to indicate more data is needed.
*/
#define GST_BASE_VIDEO_CODEC_FLOW_NEED_DATA GST_FLOW_CUSTOM_SUCCESS
/**
* GST_BASE_VIDEO_CODEC_STREAM_LOCK:
* @codec: video codec instance
*
* Obtain a lock to protect the codec function from concurrent access.
*
* Since: 0.10.22
*/
#define GST_BASE_VIDEO_CODEC_STREAM_LOCK(codec) g_static_rec_mutex_lock (&GST_BASE_VIDEO_CODEC (codec)->stream_lock)
/**
* GST_BASE_VIDEO_CODEC_STREAM_UNLOCK:
* @codec: video codec instance
*
* Release the lock that protects the codec function from concurrent access.
*
* Since: 0.10.22
*/
#define GST_BASE_VIDEO_CODEC_STREAM_UNLOCK(codec) g_static_rec_mutex_unlock (&GST_BASE_VIDEO_CODEC (codec)->stream_lock)
typedef struct _GstVideoState GstVideoState;
@ -87,6 +104,10 @@ typedef struct _GstVideoFrame GstVideoFrame;
typedef struct _GstBaseVideoCodec GstBaseVideoCodec;
typedef struct _GstBaseVideoCodecClass GstBaseVideoCodecClass;
/**
* GstVideoState:
* @caps: The caps
*/
struct _GstVideoState
{
GstCaps *caps;
@ -147,38 +168,51 @@ struct _GstVideoFrame
GList *events;
};
/**
* GstBaseVideoCodec:
*
* The opaque #GstBaseVideoCodec data structure.
*/
struct _GstBaseVideoCodec
{
GstElement element;
/*< private >*/
GstPad *sinkpad;
GstPad *srcpad;
GstElement element;
/*< protected >*/
GstPad *sinkpad;
GstPad *srcpad;
/* protects all data processing, i.e. is locked
* in the chain function, finish_frame and when
* processing serialized events */
GStaticRecMutex stream_lock;
guint64 system_frame_number;
guint64 system_frame_number;
GList *frames; /* Protected with OBJECT_LOCK */
GstVideoState state;
GstSegment segment;
GList *frames; /* Protected with OBJECT_LOCK */
GstVideoState state;
GstSegment segment;
gdouble proportion;
GstClockTime earliest_time;
gboolean discont;
/* QoS properties */
gdouble proportion;
GstClockTime earliest_time;
gboolean discont;
gint64 bytes;
gint64 time;
gint64 bytes;
gint64 time;
/* FIXME before moving to base */
void *padding[GST_PADDING_LARGE];
void *padding[GST_PADDING_LARGE];
};
/**
* GstBaseVideoCodecClass:
*
* The opaque #GstBaseVideoCodecClass data structure.
*/
struct _GstBaseVideoCodecClass
{
/*< private >*/
GstElementClass element_class;
/* FIXME before moving to base */

View file

@ -1690,7 +1690,7 @@ done:
}
/**
* gst_base_video_decoder_finish_frame:
* gst_base_video_decoder_add_to_frame:
* @base_video_decoder: a #GstBaseVideoDecoder
* @n_bytes: an encoded #GstVideoFrame
*
@ -1886,11 +1886,15 @@ exit:
* gst_base_video_decoder_get_state:
* @base_video_decoder: a #GstBaseVideoDecoder
*
* Get the current #GstVideoState
*
* Returns: #GstVideoState describing format of video data.
*/
GstVideoState *
gst_base_video_decoder_get_state (GstBaseVideoDecoder * base_video_decoder)
{
/* FIXME : Move to base codec class */
return &GST_BASE_VIDEO_CODEC (base_video_decoder)->state;
}
@ -1939,6 +1943,8 @@ gst_base_video_decoder_set_sync_point (GstBaseVideoDecoder * base_video_decoder)
* gst_base_video_decoder_get_oldest_frame:
* @base_video_decoder: a #GstBaseVideoDecoder
*
* Get the oldest pending unfinished #GstVideoFrame
*
* Returns: oldest pending unfinished #GstVideoFrame.
*/
GstVideoFrame *
@ -1947,6 +1953,8 @@ gst_base_video_decoder_get_oldest_frame (GstBaseVideoDecoder *
{
GList *g;
/* FIXME : Move to base codec class */
GST_BASE_VIDEO_CODEC_STREAM_LOCK (base_video_decoder);
g = g_list_first (GST_BASE_VIDEO_CODEC (base_video_decoder)->frames);
GST_BASE_VIDEO_CODEC_STREAM_UNLOCK (base_video_decoder);
@ -1961,6 +1969,8 @@ gst_base_video_decoder_get_oldest_frame (GstBaseVideoDecoder *
* @base_video_decoder: a #GstBaseVideoDecoder
* @frame_number: system_frame_number of a frame
*
* Get a pending unfinished #GstVideoFrame
*
* Returns: pending unfinished #GstVideoFrame identified by @frame_number.
*/
GstVideoFrame *
@ -1991,6 +2001,7 @@ gst_base_video_decoder_get_frame (GstBaseVideoDecoder * base_video_decoder,
*
* Sets src pad caps according to currently configured #GstVideoState.
*
* Returns: #TRUE if the caps were accepted downstream, else #FALSE.
*/
gboolean
gst_base_video_decoder_set_src_caps (GstBaseVideoDecoder * base_video_decoder)
@ -2042,11 +2053,11 @@ gst_base_video_decoder_set_src_caps (GstBaseVideoDecoder * base_video_decoder)
* gst_base_video_decoder_alloc_src_buffer:
* @base_video_decoder: a #GstBaseVideoDecoder
*
* Helper function that uses gst_pad_alloc_buffer_and_set_caps
* Helper function that uses @gst_pad_alloc_buffer_and_set_caps()
* to allocate a buffer to hold a video frame for @base_video_decoder's
* current #GstVideoState.
*
* Returns: allocated buffer
* Returns: (transfer full): allocated buffer
*/
GstBuffer *
gst_base_video_decoder_alloc_src_buffer (GstBaseVideoDecoder *
@ -2075,6 +2086,7 @@ gst_base_video_decoder_alloc_src_buffer (GstBaseVideoDecoder *
}
GST_BASE_VIDEO_CODEC_STREAM_UNLOCK (base_video_decoder);
return buffer;
}
@ -2083,7 +2095,7 @@ gst_base_video_decoder_alloc_src_buffer (GstBaseVideoDecoder *
* @base_video_decoder: a #GstBaseVideoDecoder
* @frame: a #GstVideoFrame
*
* Helper function that uses gst_pad_alloc_buffer_and_set_caps
* Helper function that uses @gst_pad_alloc_buffer_and_set_caps()
* to allocate a buffer to hold a video frame for @base_video_decoder's
* current #GstVideoState. Subclass should already have configured video state
* and set src pad caps.
@ -2158,8 +2170,10 @@ gst_base_video_decoder_get_max_decode_time (GstBaseVideoDecoder *
}
/**
* gst_base_video_decoder_get_oldest_frame:
* gst_base_video_decoder_class_set_capture_pattern:
* @base_video_decoder_class: a #GstBaseVideoDecoderClass
* @mask: The mask used for scanning
* @pattern: The pattern used for matching
*
* Sets the mask and pattern that will be scanned for to obtain parse sync.
* Note that a non-zero @mask implies that @scan_for_sync will be ignored.

View file

@ -95,7 +95,7 @@ GstFlowReturn _gst_base_video_decoder_error (GstBaseVideoDecoder *dec, gint weig
* enclosed in parentheses)
* @ret: variable to receive return value
*
* Utility function that audio decoder elements can use in case they encountered
* Utility function that video decoder elements can use in case they encountered
* a data processing error that may be fatal for the current "data unit" but
* need not prevent subsequent decoding. Such errors are counted and if there
* are too many, as configured in the context's max_errors, the pipeline will
@ -104,7 +104,7 @@ GstFlowReturn _gst_base_video_decoder_error (GstBaseVideoDecoder *dec, gint weig
* is logged. In either case, @ret is set to the proper value to
* return to upstream/caller (indicating either GST_FLOW_ERROR or GST_FLOW_OK).
*/
#define GST_BASE_AUDIO_DECODER_ERROR(el, w, domain, code, text, debug, ret) \
#define GST_BASE_VIDEO_DECODER_ERROR(el, w, domain, code, text, debug, ret) \
G_STMT_START { \
gchar *__txt = _gst_element_error_printf text; \
gchar *__dbg = _gst_element_error_printf debug; \
@ -122,6 +122,7 @@ G_STMT_START { \
*/
struct _GstBaseVideoDecoder
{
/*< private >*/
GstBaseVideoCodec base_video_codec;
/*< protected >*/
@ -220,8 +221,10 @@ struct _GstBaseVideoDecoder
*/
struct _GstBaseVideoDecoderClass
{
/*< private >*/
GstBaseVideoCodecClass base_video_codec_class;
/*< public >*/
gboolean (*start) (GstBaseVideoDecoder *coder);
gboolean (*stop) (GstBaseVideoDecoder *coder);
@ -248,12 +251,12 @@ struct _GstBaseVideoDecoderClass
void *padding[GST_PADDING_LARGE];
};
void gst_base_video_decoder_class_set_capture_pattern (GstBaseVideoDecoderClass *klass,
void gst_base_video_decoder_class_set_capture_pattern (GstBaseVideoDecoderClass *base_video_decoder_class,
guint32 mask, guint32 pattern);
GstVideoFrame *gst_base_video_decoder_get_frame (GstBaseVideoDecoder *coder,
GstVideoFrame *gst_base_video_decoder_get_frame (GstBaseVideoDecoder *base_video_decoder,
int frame_number);
GstVideoFrame *gst_base_video_decoder_get_oldest_frame (GstBaseVideoDecoder *coder);
GstVideoFrame *gst_base_video_decoder_get_oldest_frame (GstBaseVideoDecoder *base_video_decoder);
void gst_base_video_decoder_add_to_frame (GstBaseVideoDecoder *base_video_decoder,
int n_bytes);

View file

@ -264,6 +264,13 @@ gst_base_video_encoder_init (GstBaseVideoEncoder * base_video_encoder,
base_video_encoder->sink_clipping = TRUE;
}
/**
* gst_base_video_encoder_set_headers:
* @base_video_encoder: a #GstBaseVideoEncoder
* @headers: (transfer full): the #GstBuffer containing the codec header
*
* Set the codec headers to be sent downstream whenever requested.
*/
void
gst_base_video_encoder_set_headers (GstBaseVideoEncoder * base_video_encoder,
GstBuffer * headers)
@ -1131,11 +1138,15 @@ done:
* gst_base_video_encoder_get_state:
* @base_video_encoder: a #GstBaseVideoEncoder
*
* Get the current #GstVideoState
*
* Returns: #GstVideoState describing format of video data.
*/
const GstVideoState *
gst_base_video_encoder_get_state (GstBaseVideoEncoder * base_video_encoder)
{
/* FIXME : Move to base codec class */
return &GST_BASE_VIDEO_CODEC (base_video_encoder)->state;
}
@ -1166,7 +1177,7 @@ gst_base_video_encoder_set_latency (GstBaseVideoEncoder * base_video_encoder,
/**
* gst_base_video_encoder_set_latency_fields:
* @base_video_encoder: a #GstBaseVideoEncoder
* @fields: latency in fields
* @n_fields: latency in fields
*
* Informs baseclass of encoding latency in terms of fields (both min
* and max latency).
@ -1193,6 +1204,8 @@ gst_base_video_encoder_set_latency_fields (GstBaseVideoEncoder *
* gst_base_video_encoder_get_oldest_frame:
* @base_video_encoder: a #GstBaseVideoEncoder
*
* Get the oldest unfinished pending #GstVideoFrame
*
* Returns: oldest unfinished pending #GstVideoFrame
*/
GstVideoFrame *
@ -1201,6 +1214,8 @@ gst_base_video_encoder_get_oldest_frame (GstBaseVideoEncoder *
{
GList *g;
/* FIXME : Move to base codec class */
GST_BASE_VIDEO_CODEC_STREAM_LOCK (base_video_encoder);
g = g_list_first (GST_BASE_VIDEO_CODEC (base_video_encoder)->frames);
GST_BASE_VIDEO_CODEC_STREAM_UNLOCK (base_video_encoder);

View file

@ -70,12 +70,12 @@ typedef struct _GstBaseVideoEncoderClass GstBaseVideoEncoderClass;
/**
* GstBaseVideoEncoder:
* @element: the parent element.
*
* The opaque #GstBaseVideoEncoder data structure.
*/
struct _GstBaseVideoEncoder
{
/*< private >*/
GstBaseVideoCodec base_video_codec;
/*< protected >*/
@ -115,6 +115,8 @@ struct _GstBaseVideoEncoder
* GstVideoState fields have already been
* set according to provided caps.
* @handle_frame: Provides input frame to subclass.
* @reset: Optional.
* Allows subclass (codec) to perform post-seek semantics reset.
* @finish: Optional.
* Called to request subclass to dispatch any pending remaining
* data (e.g. at EOS).
@ -133,6 +135,7 @@ struct _GstBaseVideoEncoder
*/
struct _GstBaseVideoEncoderClass
{
/*< private >*/
GstBaseVideoCodecClass base_video_codec_class;
/*< public >*/
@ -164,9 +167,9 @@ struct _GstBaseVideoEncoderClass
GType gst_base_video_encoder_get_type (void);
const GstVideoState* gst_base_video_encoder_get_state (GstBaseVideoEncoder *coder);
const GstVideoState* gst_base_video_encoder_get_state (GstBaseVideoEncoder *base_video_encoder);
GstVideoFrame* gst_base_video_encoder_get_oldest_frame (GstBaseVideoEncoder *coder);
GstVideoFrame* gst_base_video_encoder_get_oldest_frame (GstBaseVideoEncoder *base_video_encoder);
GstFlowReturn gst_base_video_encoder_finish_frame (GstBaseVideoEncoder *base_video_encoder,
GstVideoFrame *frame);
@ -175,7 +178,7 @@ void gst_base_video_encoder_set_latency (GstBaseVideoEncoder *
void gst_base_video_encoder_set_latency_fields (GstBaseVideoEncoder *base_video_encoder,
int n_fields);
void gst_base_video_encoder_set_headers (GstBaseVideoEncoder *base_video_encoder,
GstBuffer *headers);
GstBuffer *headers);
G_END_DECLS
#endif