[gst-devel] docs - the easy way for you

[Ronald S. Bultje]

Hi Stefan,

let's give it a try.

On Tue, 2004-08-31 at 16:38, Stefan Kost wrote:
[..]

> GLOBAL_REGISTRY_DIR
> GLOBAL_REGISTRY_FILE
> GLOBAL_REGISTRY_FILE_TMP

Those should be hidden. I don't think applications or plugins are
supposed to explicitely touch the registry anyway. They should use the
gstreamer object (signal, function) hooks for that.

> GST_BOILERPLATE
> GST_BOILERPLATE_FULL

Those two automate the boilerplate code for GObjects. They create a
_get_type() function for the given object and add definitions (but not
implmentations) for the _init(), class_init() and base_init() functions.
The object still actually has to implement those later. The _FULL
variant also allows for additional code to be executed during the type
creation. Ususally, this is used for explicit debug category creation or
so, but it could also be used for interface initialization to the object
type.

> GST_BUFFER_DURATION

duration in nanoseconds of the data in the buffer. GST_CLOCK_TIME_NONE
if unknown.

> GST_BUFFER_DURATION_IS_VALID

tests if the duration is known.

> GST_BUFFER_FREE_DATA_FUNC

a function that should be called if the buffer has no more references
left. Elements that utilize hardware memory could use this to re-queue
the buffer after it's been unreferenced. If no free_data_func has been
provided, the default will be used which simply deallocates the memory
region and the GstBuffer object. Manual implementations that want to
free their own memory but don't do anything special otherwise are
suggested to set the GST_BUFFER_DONTFREE flag on the buffer and call the
default data free function (gst_buffer_default_free()) from their manual
implementation.

> GST_BUFFER_PRIVATE

private data for the buffer. This can be used to store a pointer to the
object that can then be retrieved in something like the
BUFFER_FREE_DATA_FUNC.

> GST_BUFFER_TIMESTAMP_IS_VALID

tests if the timestamp of the buffer is known.

> GST_CAPS_ANY

means that the element/pad can output 'anything'. Useful for elements
that output unknown media, such as filesrc.

> GST_CAPS_FLAGS_ANY

flags that this caps has no specific content, but can contain anything.

> GST_CAPS_NONE

the opposite of GST_CAPS_ANY: it means that the pad/element outputs an
undefined media type that can not be detected.

> GST_CLOCK_TIME_IS_VALID

tests if the given time (in nanoseconds) is an allowed value (anything
but GST_CLOCK_TIME_NONE).

> GST_DEBUG_BG_MASK
> GST_DEBUG_CAPS
> GST_DEBUG_FG_MASK
> GST_DEBUG_FORMAT_MASK

I'm pretty sure you want those to be private.

> GST_ELEMENT_ERROR

utility function that elements can use in case they encountered a fatal
data processing error. The pipeline will throw an error signal and the
application will be requested to stop further media processing.

> GST_FOURCC_ARGS
> GST_FOURCC_FORMAT

can be used to properly output a fourcc (a guint32) value in a
printf()-style text message. FORMAT is to be used as format, args as the
argument:

printf ("fourcc: %" GST_FOURCC_FORMAT "\n", GST_FOURCC_ARGS (fcc));

> GST_HAVE_UNALIGNED_ACCESS

private.

> GST_IMPLEMENTS_INTERFACE_CHECK_INSTANCE_CAST
> GST_IMPLEMENTS_INTERFACE_CHECK_INSTANCE_TYPE

similar to the glib cast/check functions, but those also check if the
given object indicate that their instance supports running this
interface. Can be used as extensions to the standard glib cast/check
object macros. They should not be used in the default glib-style macros,
though (some interfaces do this - will be fixed in 0.9).

> GST_MAKE_FOURCC

will transform four characters into a host-endiannness guint32 fourcc:

guint32 fourcc = GST_MAKE_FOURCC ('M','J','P','G');

> GST_PAD_CONNECT_DELAYED
> GST_PAD_CONNECT_DONE
> GST_PAD_CONNECT_OK
> GST_PAD_CONNECT_REFUSED

Deprecated cousins of their _LINK_ counterparts.

> GST_PAD_LINK_FAILED
> GST_PAD_LINK_SUCCESSFUL

macros to test if the given GstPadLinkReturn value indicates a
successfull negotiation step (OK/DONE) or not (REFUSED/DELAYED).

> GST_PLUGIN_DEFINE
> GST_PLUGIN_DEFINE_STATIC

you already had those, I believe. Those are to define standard
properties of a plugin through which GStreamer can load them. The
_STATIC counterpart is for static (non-loadable, compiled-in) elements.

> GST_RANK_MARGINAL
> GST_RANK_NONE
> GST_RANK_PRIMARY
> GST_RANK_SECONDARY

Element ranks. Defines the order in which the autoplugger (or similar
rank-picking mechanisms) will choose this element over an alternative
with the same function.

> GST_READ_UINT16_BE
> GST_READ_UINT16_LE
> GST_READ_UINT32_BE
> GST_READ_UINT32_LE
> GST_READ_UINT64_BE
> GST_READ_UINT64_LE
> GST_READ_UINT8

macros to read the given value types from a binary input stream, taking
byte alignment and all that into account.

guchar *buf = ...;
guint32 width = GST_READ_UINT32_LE (buf);

> GST_SCHEDULER_DEFAULT_NAME

Hide?

> GST_STATIC_CAPS

creates a static caps from an input string. This can be used in pad
templates.

> GST_STATIC_CAPS_ANY

static any caps.

> GST_STATIC_CAPS_NONE

static none caps.

> GST_STR_FOURCC

creates a fourcc from an input string. The input string should consisnt
of at least four characters (this is not checked for!).

guint32 fourcc = GST_STR_FOURCC("MJPG");

> GST_TAG_ALBUM
> GST_TAG_ALBUM_GAIN
> GST_TAG_ALBUM_PEAK
> GST_TAG_ALBUM_VOLUME_COUNT
> GST_TAG_ALBUM_VOLUME_NUMBER
> GST_TAG_ARTIST
> GST_TAG_AUDIO_CODEC
> GST_TAG_BITRATE
> GST_TAG_CODEC
> GST_TAG_COMMENT
> GST_TAG_CONTACT
> GST_TAG_COPYRIGHT
> GST_TAG_DATE
> GST_TAG_DESCRIPTION
> GST_TAG_DURATION
> GST_TAG_ENCODER
> GST_TAG_ENCODER_VERSION
> GST_TAG_GENRE
> GST_TAG_ISRC
> GST_TAG_LICENSE
> GST_TAG_LOCATION
> GST_TAG_MAXIMUM_BITRATE
> GST_TAG_MINIMUM_BITRATE
> GST_TAG_NOMINAL_BITRATE
> GST_TAG_ORGANIZATION
> GST_TAG_PERFORMER
> GST_TAG_SERIAL
> GST_TAG_TITLE
> GST_TAG_TRACK_COUNT
> GST_TAG_TRACK_GAIN
> GST_TAG_TRACK_NUMBER
> GST_TAG_TRACK_PEAK
> GST_TAG_VERSION
> GST_TAG_VIDEO_CODEC

Those are all tags, I suppose I don't need to explain them.

> GST_TIME_ARGS
> GST_TIME_FORMAT

printf()-style format and argument macros for printing times (in
nanoseconds, a guint64) in a human-readable format (hh:mm:ss.xxx).

guint64 time = 0;
printf ("Time: %" GST_TIME_FORMAT "\n", GST_TIME_ARGS (time));

> GST_TYPE_BUFFER_FLAG

retrieve the flags from a buffer.

> GST_TYPE_CLOCK_ENTRY_STATUS
> GST_TYPE_CLOCK_ENTRY_TYPE
> GST_TYPE_CLOCK_FLAGS
> GST_TYPE_CLOCK_RETURN
> GST_TYPE_CORE_ERROR
> GST_TYPE_CPU_FLAGS
> GST_TYPE_DATA
> GST_TYPE_DATA_FLAGS
> GST_TYPE_DEBUG_COLOR_FLAGS
> GST_TYPE_DEBUG_LEVEL
> GST_TYPE_DOUBLE_RANGE
> GST_TYPE_ELEMENT
> GST_TYPE_ELEMENT_FACTORY
> GST_TYPE_ELEMENT_FLAGS
> GST_TYPE_ELEMENT_STATE
> GST_TYPE_ELEMENT_STATE_RETURN
> GST_TYPE_EVENT
> GST_TYPE_EVENT_FLAG
> GST_TYPE_EVENT_TYPE
> GST_TYPE_FIXED_LIST
> GST_TYPE_FORMAT
> GST_TYPE_FOURCC
> GST_TYPE_FRACTION
> GST_TYPE_GHOST_PAD
> GST_TYPE_G_ERROR
> GST_TYPE_IMPLEMENTS_INTERFACE
> GST_TYPE_INDEX_CERTAINTY
> GST_TYPE_INDEX_ENTRY
> GST_TYPE_INDEX_ENTRY_TYPE
> GST_TYPE_INDEX_FACTORY
> GST_TYPE_INDEX_FLAGS
> GST_TYPE_INDEX_LOOKUP_METHOD
> GST_TYPE_INDEX_RESOLVER_METHOD
> GST_TYPE_INT_RANGE
> GST_TYPE_LIBRARY_ERROR
> GST_TYPE_LIST
> GST_TYPE_OBJECT
> GST_TYPE_OBJECT_FLAGS
> GST_TYPE_PAD
> GST_TYPE_PAD_DIRECTION
> GST_TYPE_PAD_FLAGS
> GST_TYPE_PAD_LINK_RETURN
> GST_TYPE_PAD_PRESENCE
> GST_TYPE_PAD_TEMPLATE
> GST_TYPE_PAD_TEMPLATE_FLAGS
> GST_TYPE_PARSE_ERROR
> GST_TYPE_PLUGIN
> GST_TYPE_PLUGIN_ERROR
> GST_TYPE_QUERY_TYPE
> GST_TYPE_REGISTRY_FLAGS
> GST_TYPE_REGISTRY_RETURN
> GST_TYPE_RESOURCE_ERROR
> GST_TYPE_RESULT
> GST_TYPE_SCHEDULER_FACTORY
> GST_TYPE_SCHEDULER_FLAGS
> GST_TYPE_SCHEDULER_STATE
> GST_TYPE_SEEK_ACCURACY
> GST_TYPE_SEEK_TYPE
> GST_TYPE_STREAM_ERROR
> GST_TYPE_STRUCTURE
> GST_TYPE_SYSTEM_CLOCK
> GST_TYPE_TAG_FLAG
> GST_TYPE_TAG_LIST
> GST_TYPE_TAG_MERGE_MODE
> GST_TYPE_TAG_SETTER
> GST_TYPE_THREAD
> GST_TYPE_THREAD_STATE
> GST_TYPE_TYPE_FIND_FACTORY
> GST_TYPE_TYPE_FIND_PROBABILITY
> GST_TYPE_URI
> GST_TYPE_URI_HANDLER
> GST_TYPE_URI_TYPE

all GTypes. Does glib document all those? Those shouldn't be too hard.
If you need specific information for any of them, just ask.

> GST_VALUE_EQUAL
> GST_VALUE_GREATER_THAN
> GST_VALUE_LESS_THAN
> GST_VALUE_UNORDERED

Indicates if the two values provided to a comparison function
(gst_value_compare()) are lesser than, greater than or equal to each
other. If this cannot be said (e.g. because lesser than or greater than
makes no sense for those particular value comparisons), you'll get
unordered, which means as much as "don't know".

> GST_VALUE_HOLDS_CAPS
> GST_VALUE_HOLDS_DOUBLE_RANGE
> GST_VALUE_HOLDS_FIXED_LIST
> GST_VALUE_HOLDS_FOURCC
> GST_VALUE_HOLDS_FRACTION
> GST_VALUE_HOLDS_INT_RANGE
> GST_VALUE_HOLDS_LIST

Macros that check whether the given GValue holds a specific value
(gst-defined) type. Similar to the G_VALUE_HOLDS_{INT,LONG,...} macros.

> GST_WRITE_UINT16_BE
> GST_WRITE_UINT16_LE
> GST_WRITE_UINT32_BE
> GST_WRITE_UINT32_LE
> GST_WRITE_UINT64_BE
> GST_WRITE_UINT64_LE
> GST_WRITE_UINT8

Write a given value type into a buffer. The opposite of the _READ_
macros. Take alignment and all that into account.

guchar buf[4];
GST_WRITE_UINT32_LE (buf, 250);

> GstBin::element-added
> GstBin::element-removed

will be signalled if an element was removed/added. Can be used to take
action as a result of this in an application or element.

> GstQueue::overrun
> GstQueue::running
> GstQueue::underrun

will be signalled if the buffer became full (overrun), became empty
(underrun) or became non-empty or non-full (running). A buffer is full
or empty if the total amount of data inside it (num-buffers, time, size)
is lower than the boundary values which can be set through the GObject
properties.

> GstBin
> GstBufferFreeDataFunc
> GstCaps
> GstClock
> GstCoreError
> GstDebugMessage
> GstElement
> GstElementFactory
> GstElementState
> GstElementStateReturn
> GstEvent
> GstFilterFunc
> GstGhostPad
> GstImplementsInterface
> GstIndex
> GstLibraryError
> GstLogFunction
> GstObject
> GstPad
> GstPadBufferAllocFunction
> GstPadConnectFunction
> GstPadConnectReturn
> GstPadFixateFunction
> GstPadLink
> GstPadUnlinkFunction
> GstParseError
> GstPipeline
> GstPluginExitFunc
> GstPluginFeature
> GstPluginFeatureFilter
> GstPluginFilter
> GstQueue
> GstQueueSize
> GstRegistry
> GstResourceError
> GstResult
> GstScheduler
> GstSchedulerFactory
> GstStaticCaps
> GstStaticPadTemplate
> GstStreamError
> GstStructure
> GstStructureForeachFunc
> GstSystemClock
> GstTagFlag
> GstTagForeachFunc
> GstTagList
> GstTagMergeFunc
> GstTagMergeMode
> GstTagSetter
> GstTagSetterIFace
> GstThread
> GstThread::shutdown
> GstTrace
> GstTraceEntry
> GstTrashStack
> GstTrashStackElement
> GstTypeFind
> GstTypeFindFunction
> GstTypeFindProbability
> GstTypeNameData
> GstURIHandler
> GstURIType
> GstValueCompareFunc
> GstValueDeserializeFunc
> GstValueIntersectFunc
> GstValueSerializeFunc
> GstValueSubtractFunc
> GstValueTable
> GstValueUnionFunc
> GstXML

Most of those are simple, well, typedefs. Similar question to the _TYPE_
one: does glib document this?

> LOCAL_REGISTRY_DIR
> LOCAL_REGISTRY_FILE
> LOCAL_REGISTRY_FILE_TMP

Same as above for GLOBAL. Probably hide.

> REGISTRY_DIR_PERMS
> REGISTRY_FILE_PERMS
> REGISTRY_TMPFILE_PERMS

Probably same.

> gst_buffer_is_writable

tests if you can safely write data into a buffer's data array.

> gst_element_connect
> gst_element_connect_filtered
> gst_element_connect_many
> gst_element_connect_pads
> gst_element_disconnect

deprecated cousins of the link/unlink counterparts.

> gst_info

I think this is similar to g_print. Should probably be removed. I think
it is actually deprecated. Unsure.

> gst_pad_connect
> gst_pad_connect_filtered
> gst_pad_disconnect
> gst_pad_proxy_connect
> gst_pad_set_connect_function

Deprecated counterparts of link/unlink.

> gst_tag_get_description

gets the human-readable description of the meaning of a specific tag
type.

> gst_tag_list_get_boolean
> gst_tag_list_get_boolean_index
> gst_tag_list_get_char
> gst_tag_list_get_char_index
> gst_tag_list_get_double
> gst_tag_list_get_double_index
> gst_tag_list_get_float
> gst_tag_list_get_float_index
> gst_tag_list_get_int
> gst_tag_list_get_int64
> gst_tag_list_get_int64_index
> gst_tag_list_get_int_index
> gst_tag_list_get_long
> gst_tag_list_get_long_index
> gst_tag_list_get_pointer
> gst_tag_list_get_pointer_index
> gst_tag_list_get_string
> gst_tag_list_get_string_index
> gst_tag_list_get_uchar
> gst_tag_list_get_uchar_index
> gst_tag_list_get_uint
> gst_tag_list_get_uint64
> gst_tag_list_get_uint64_index
> gst_tag_list_get_uint_index
> gst_tag_list_get_ulong
> gst_tag_list_get_ulong_index

Gets the first or the index'ed tag value from a list.

> gst_type_is_fixed

Returns if the given GType, if available in a GstStructure (or any other
container) will contain a "fixed" (which means: one possible value) or
an "unfixed" (which means: multiple possible values, such as data lists
or data ranges) value.

Unknown to me (so free for others to comment on):

GST_BUFFER_MAXSIZE_IS_VALID
GST_BUFFER_MAXSIZE_NONE
GST_BUFFER_OFFSET_END
GST_BUFFER_OFFSET_END_IS_VALID
GST_BUFFER_OFFSET_IS_VALID
GST_BUFFER_OFFSET_NONE
GST_CALL_PARENT
GST_CALL_PARENT_WITH_DEFAULT
GST_CAN_INLINE
GST_CAPS_IS_SIMPLE
GST_CORE_ERROR
GST_DISABLE_ALLOC_TRACE
GST_DISABLE_ENUMTYPES
GST_DISABLE_INDEX
GST_DISABLE_LOADSAVE
GST_DISABLE_LOADSAVE_REGISTRY
GST_DISABLE_PARSE
GST_DISABLE_PLUGIN
GST_DISABLE_REGISTRY
GST_DISABLE_TRACE
GST_DISABLE_URI
GST_ERROR_SYSTEM
GST_EVENT_ANY
GST_GNUC_CONSTRUCTOR
GST_INLINE_FUNC
GST_IS_GHOST_PAD_FAST
GST_IS_PAD_FAST
GST_LIBRARY_ERROR
GST_LICENSE_UNKNOWN
GST_PADDING
GST_PADDING_INIT
GST_PAD_IS_DISPATCHING
GST_PAD_IS_NEGOTIATING
GST_PARSE_ERROR
GST_PTR_FORMAT
GST_RESOURCE_ERROR
GST_STATIC_CAPS_PREFERRED
GST_STREAM_ERROR
GST_TYPE_ALLOC_TRACE_FLAGS
GST_TYPE_ASSOC_FLAGS
GST_TYPE_BIN_FLAGS
GST_URI_TYPE_IS_VALID
SMP_LOCK
gst_alloc_trace_live_all
gst_caps_get_preferred
gst_caps_is_simple
gst_caps_set_preferred
gst_caps_use_preferred
gst_core_error_quark
gst_debug_category_set_threshold_for_name
gst_debug_category_unset_threshold_for_name
gst_debug_print_stack_trace
gst_debug_reset_log_function
gst_debug_set_log_function
gst_element_factory_get_klass
gst_error_get_message
gst_index_entry_get_type
gst_library_error_quark
gst_pad_is_negotiated
gst_parse_error_quark
gst_plugin_feature_filter
gst_plugin_feature_get_rank
gst_plugin_feature_type_name_filter
gst_plugin_list_feature_filter
gst_resource_error_quark
gst_stream_error_quark
gst_structure_get_name_id
gst_thread_current
gst_trace_add_entry
gst_trace_destroy
gst_trace_flush
gst_trace_get_offset
gst_trace_get_remaining
gst_trace_get_size
gst_trace_new
gst_trace_read_tsc
gst_trace_set_default
gst_trace_text_flush
gst_value_can_intersect
gst_value_deserialize
gst_value_init_and_copy
gst_value_register
gst_value_register_intersect_func
gst_value_serialize
gst_vgint
gst_vgpointer
gst_vgulong

HTH,

Ronald

-- 
Ronald S. Bultje <rbultje at ronald.bitfreak.net>