Commit 6f4a7330 authored by Wim Taymans's avatar Wim Taymans

metadata: Rename to GstMeta

Rename to the shorter GstMeta
Add docs
Add api to get metadata by API
parent d7b989bf
......@@ -79,6 +79,7 @@ Windows. It is released under the GNU Library General Public License
<xi:include href="xml/gstindexfactory.xml" />
<xi:include href="xml/gstiterator.xml" />
<xi:include href="xml/gstmessage.xml" />
<xi:include href="xml/gstmeta.xml" />
<xi:include href="xml/gstminiobject.xml" />
<xi:include href="xml/gstobject.xml" />
<xi:include href="xml/gstpad.xml" />
......
......@@ -209,25 +209,11 @@ gst_buffer_span
gst_buffer_join
gst_buffer_merge
GstBufferMeta
GST_BUFFER_META_TRACE_NAME
gst_buffer_get_meta_by_api
gst_buffer_get_meta
gst_buffer_remove_meta
gst_buffer_iterate_meta
GstBufferMetaInfo
GstMetaInitFunction
GstMetaFreeFunction
GstMetaCopyFunction
GstMetaSubFunction
GstMetaSerializeFunction
GstMetaDeserializeFunction
gst_buffer_meta_get_info
gst_buffer_meta_register_info
<SUBSECTION Standard>
GstBufferClass
GST_BUFFER
......@@ -245,6 +231,22 @@ gst_buffer_flag_get_type
gst_buffer_copy_flags_get_type
</SECTION>
<SECTION>
<FILE>gstmeta</FILE>
<TITLE>GstMeta</TITLE>
GstMeta
GstMetaInfo
GST_META_TRACE_NAME
GstMetaInitFunction
GstMetaFreeFunction
GstMetaCopyFunction
GstMetaSubFunction
GstMetaSerializeFunction
GstMetaDeserializeFunction
gst_meta_register
gst_meta_get_info
</SECTION>
<SECTION>
<FILE>gstbufferlist</FILE>
<TITLE>GstBufferList</TITLE>
......
......@@ -51,7 +51,6 @@ libgstreamer_@GST_MAJORMINOR@_la_SOURCES = \
gstbin.c \
gstbuffer.c \
gstbufferlist.c \
gstbuffermeta.c \
gstbus.c \
gstcaps.c \
gstchildproxy.c \
......@@ -72,6 +71,7 @@ libgstreamer_@GST_MAJORMINOR@_la_SOURCES = \
gstiterator.c \
gstatomicqueue.c \
gstmessage.c \
gstmeta.c \
gstminiobject.c \
gstpad.c \
gstpadtemplate.c \
......@@ -143,7 +143,6 @@ gst_headers = \
gstbin.h \
gstbuffer.h \
gstbufferlist.h \
gstbuffermeta.h \
gstbus.h \
gstcaps.h \
gstchildproxy.h \
......@@ -166,6 +165,7 @@ gst_headers = \
gstatomicqueue.h \
gstmacros.h \
gstmessage.h \
gstmeta.h \
gstminiobject.h \
gstpad.h \
gstpadtemplate.h \
......
......@@ -668,7 +668,7 @@ init_post (GOptionContext * context, GOptionGroup * group, gpointer data,
_gst_format_initialize ();
_gst_query_initialize ();
_gst_caps_initialize ();
_gst_buffer_meta_init ();
_gst_meta_init ();
g_type_class_ref (gst_object_get_type ());
g_type_class_ref (gst_pad_get_type ());
......
......@@ -130,15 +130,15 @@
GType _gst_buffer_type = 0;
typedef struct _GstBufferMetaItem GstBufferMetaItem;
typedef struct _GstMetaItem GstMetaItem;
struct _GstBufferMetaItem
struct _GstMetaItem
{
GstBufferMetaItem *next;
GstBufferMeta meta;
GstMetaItem *next;
GstMeta meta;
};
#define ITEM_SIZE(info) ((info)->size + sizeof (GstBufferMetaItem))
#define ITEM_SIZE(info) ((info)->size + sizeof (GstMetaItem))
/* buffer alignment in bytes
* an alignment of 8 would be the same as malloc() guarantees
......@@ -199,7 +199,7 @@ void
gst_buffer_copy_metadata (GstBuffer * dest, const GstBuffer * src,
GstBufferCopyFlags flags)
{
GstBufferMetaItem *walk;
GstMetaItem *walk;
g_return_if_fail (dest != NULL);
g_return_if_fail (src != NULL);
......@@ -238,8 +238,8 @@ gst_buffer_copy_metadata (GstBuffer * dest, const GstBuffer * src,
}
for (walk = src->priv; walk; walk = walk->next) {
GstBufferMeta *meta = &walk->meta;
const GstBufferMetaInfo *info = meta->info;
GstMeta *meta = &walk->meta;
const GstMetaInfo *info = meta->info;
if (info->copy_func)
info->copy_func (dest, meta, src);
......@@ -289,7 +289,7 @@ _gst_buffer_copy (GstBuffer * buffer)
static void
_gst_buffer_free (GstBuffer * buffer)
{
GstBufferMetaItem *walk, *next;
GstMetaItem *walk, *next;
g_return_if_fail (buffer != NULL);
......@@ -307,15 +307,15 @@ _gst_buffer_free (GstBuffer * buffer)
/* free metadata */
for (walk = buffer->priv; walk; walk = next) {
GstBufferMeta *meta = &walk->meta;
const GstBufferMetaInfo *info = meta->info;
GstMeta *meta = &walk->meta;
const GstMetaInfo *info = meta->info;
/* call free_func if any */
if (info->free_func)
info->free_func (meta, buffer);
/* and free the slice */
next = walk->next;
g_slice_free (GstBufferMetaItem, walk);
g_slice_free (GstMetaItem, walk);
}
g_slice_free1 (GST_MINI_OBJECT_SIZE (buffer), buffer);
......@@ -594,7 +594,7 @@ gst_buffer_create_sub (GstBuffer * buffer, guint offset, guint size)
GstBuffer *subbuffer;
GstBuffer *parent;
gboolean complete;
GstBufferMetaItem *walk;
GstMetaItem *walk;
g_return_val_if_fail (buffer != NULL, NULL);
g_return_val_if_fail (buffer->mini_object.refcount > 0, NULL);
......@@ -659,8 +659,8 @@ gst_buffer_create_sub (GstBuffer * buffer, guint offset, guint size)
}
/* call subbuffer functions for metadata */
for (walk = buffer->priv; walk; walk = walk->next) {
GstBufferMeta *meta = &walk->meta;
const GstBufferMetaInfo *info = meta->info;
GstMeta *meta = &walk->meta;
const GstMetaInfo *info = meta->info;
if (info->sub_func)
info->sub_func (subbuffer, meta, buffer, offset, size);
......@@ -775,59 +775,88 @@ gst_buffer_span (GstBuffer * buf1, guint32 offset, GstBuffer * buf2,
/**
* gst_buffer_get_meta:
* gst_buffer_get_meta_by_api:
* @buffer: a #GstBuffer
* @info: a #GstBufferMetaInfo
* @api: a #GQuark
*
* Retrieve the metadata for @info on @buffer.
* Retrieve the metadata for @api on @buffer. @api is the #GQuark of the
* metadata structure API.
*
* If there is no metadata for @info on @buffer, this function will return
* %NULL unless the @create flags is set to %TRUE, in which case a new
* metadata for @info will be created.
* If there is no metadata for @api on @buffer, this function will return
* %NULL.
*
* Returns: the metadata for @info on @buffer or %NULL when there is no such
* metadata on @buffer and @create is %FALSE.
* Returns: the metadata for @api on @buffer or %NULL when there is no such
* metadata on @buffer.
*/
GstBufferMeta *
gst_buffer_get_meta (GstBuffer * buffer, const GstBufferMetaInfo * info,
gboolean create)
GstMeta *
gst_buffer_get_meta_by_api (GstBuffer * buffer, GQuark api)
{
GstBufferMetaItem *walk;
GstBufferMeta *result = NULL;
GstMetaItem *walk;
GstMeta *result = NULL;
g_return_val_if_fail (buffer != NULL, NULL);
g_return_val_if_fail (info != NULL, NULL);
g_return_val_if_fail (api != 0, NULL);
/* loop over the metadata items until we find the one with the
* requested info. FIXME, naive implementation using a list */
for (walk = buffer->priv; walk; walk = walk->next) {
GstBufferMeta *meta = &walk->meta;
if (meta->info == info) {
GstMeta *meta = &walk->meta;
if (meta->info->api == api) {
result = meta;
break;
}
}
/* not found, check if we need to create */
if (!result && create) {
return result;
}
/**
* gst_buffer_get_meta:
* @buffer: a #GstBuffer
* @info: a #GstMetaInfo
* @create: create when needed
*
* Get the metadata for the api in @info on buffer. When there is no such
* metadata and @create is TRUE, a new metadata form @info is created and added
* to @buffer.
*
* Note that the result metadata might not be of the implementation @info when
* it was already on the buffer.
*
* Returns: the metadata for @info on @buffer.
*/
GstMeta *
gst_buffer_get_meta (GstBuffer * buffer, const GstMetaInfo * info,
gboolean create)
{
GstMeta *result = NULL;
GstMetaItem *item;
g_return_val_if_fail (buffer != NULL, NULL);
g_return_val_if_fail (info != 0, NULL);
result = gst_buffer_get_meta_by_api (buffer, info->api);
if (result == NULL && create) {
/* create a new slice */
GST_DEBUG ("alloc metadata of size %" G_GSIZE_FORMAT, info->size);
walk = g_slice_alloc (ITEM_SIZE (info));
result = &walk->meta;
item = g_slice_alloc (ITEM_SIZE (info));
result = &item->meta;
result->info = info;
/* call the init_func when needed */
if (info->init_func)
info->init_func (result, buffer);
/* and add to the list of metadata */
walk->next = buffer->priv;
buffer->priv = walk;
item->next = buffer->priv;
buffer->priv = item;
}
return result;
}
/**
* gst_buffer_remove_meta:
* @buffer: a #GstBuffer
* @info: a #GstBufferMetaInfo
* @info: a #GstMetaInfo
*
* Remove the metadata for @info on @buffer.
*
......@@ -835,18 +864,20 @@ gst_buffer_get_meta (GstBuffer * buffer, const GstBufferMetaInfo * info,
* metadata was on @buffer.
*/
gboolean
gst_buffer_remove_meta (GstBuffer * buffer, const GstBufferMetaInfo * info)
gst_buffer_remove_meta (GstBuffer * buffer, GstMeta * meta)
{
GstBufferMetaItem *walk, *prev;
GstMetaItem *walk, *prev;
g_return_val_if_fail (buffer != NULL, FALSE);
g_return_val_if_fail (info != NULL, FALSE);
g_return_val_if_fail (meta != NULL, FALSE);
/* find the metadata and delete */
prev = buffer->priv;
for (walk = prev; walk; walk = walk->next) {
GstBufferMeta *meta = &walk->meta;
if (meta->info == info) {
GstMeta *m = &walk->meta;
if (m == meta) {
const GstMetaInfo *info = meta->info;
/* remove from list */
if (buffer->priv == walk)
buffer->priv = walk->next;
......@@ -854,9 +885,10 @@ gst_buffer_remove_meta (GstBuffer * buffer, const GstBufferMetaInfo * info)
prev->next = walk->next;
/* call free_func if any */
if (info->free_func)
info->free_func (meta, buffer);
info->free_func (m, buffer);
/* and free the slice */
g_slice_free1 (ITEM_SIZE (info), meta);
g_slice_free1 (ITEM_SIZE (info), walk);
break;
}
prev = walk;
......@@ -869,22 +901,22 @@ gst_buffer_remove_meta (GstBuffer * buffer, const GstBufferMetaInfo * info)
* @buffer: a #GstBuffer
* @state: an opaque state pointer
*
* Retrieve the next #GstBufferMeta after @current. If @state points
* Retrieve the next #GstMeta after @current. If @state points
* to %NULL, the first metadata is returned.
*
* @state will be updated with an opage state pointer
*
* Returns: The next #GstBufferMeta or %NULL when there are no more items.
* Returns: The next #GstMeta or %NULL when there are no more items.
*/
GstBufferMeta *
GstMeta *
gst_buffer_iterate_meta (GstBuffer * buffer, gpointer * state)
{
GstBufferMetaItem **meta;
GstMetaItem **meta;
g_return_val_if_fail (buffer != NULL, NULL);
g_return_val_if_fail (state != NULL, NULL);
meta = (GstBufferMetaItem **) state;
meta = (GstMetaItem **) state;
if (*meta == NULL)
/* state NULL, move to first item */
*meta = buffer->priv;
......
......@@ -470,13 +470,14 @@ gboolean gst_buffer_is_span_fast (GstBuffer *buf1, GstBuffer *buf
GstBuffer* gst_buffer_span (GstBuffer *buf1, guint32 offset, GstBuffer *buf2, guint32 len);
/* metadata */
#include <gst/gstbuffermeta.h>
#include <gst/gstmeta.h>
GstBufferMeta * gst_buffer_get_meta (GstBuffer *buffer, const GstBufferMetaInfo *info,
gboolean create);
gboolean gst_buffer_remove_meta (GstBuffer *buffer, const GstBufferMetaInfo *info);
GstMeta * gst_buffer_get_meta_by_api (GstBuffer *buffer, GQuark api);
GstBufferMeta * gst_buffer_iterate_meta (GstBuffer *buffer, gpointer *state);
GstMeta * gst_buffer_get_meta (GstBuffer *buffer, const GstMetaInfo *info, gboolean create);
gboolean gst_buffer_remove_meta (GstBuffer *buffer, GstMeta *meta);
GstMeta * gst_buffer_iterate_meta (GstBuffer *buffer, gpointer *state);
/**
* gst_value_set_buffer:
......
/* GStreamer
* Copyright (C) 2009 Wim Taymans <wim.taymans@gmail.com>
* Copyright (C) 2011 Wim Taymans <wim.taymans@gmail.com>
*
* gstbuffermeta.c: Buffer metadata operations
* gstmeta.c: metadata operations
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
......@@ -20,7 +20,7 @@
*/
/**
* SECTION:gstbuffermeta
* SECTION:gstmeta
* @short_description: Buffer metadata
*
* Last reviewed on December 17th, 2009 (0.10.26)
......@@ -28,7 +28,7 @@
#include "gst_private.h"
#include "gstbuffer.h"
#include "gstbuffermeta.h"
#include "gstmeta.h"
#include "gstinfo.h"
#include "gstutils.h"
......@@ -36,55 +36,73 @@ static GHashTable *metainfo = NULL;
static GStaticRWLock lock = G_STATIC_RW_LOCK_INIT;
void
_gst_buffer_meta_init (void)
_gst_meta_init (void)
{
metainfo = g_hash_table_new (g_str_hash, g_str_equal);
}
/**
* gst_buffer_meta_register_info:
* @info: a #GstBufferMetaInfo
* gst_meta_register_info:
* @info: a #GstMetaInfo
*
* Register a #GstBufferMetaInfo. The same @info can be retrieved later with
* gst_buffer_meta_get_info() by using the name as the key.
* Register a #GstMetaInfo. The same @info can be retrieved later with
* gst_meta_get_info() by using @impl as the key.
*
* Returns: a #GstBufferMetaInfo that can be used to access buffer metadata.
* Returns: a #GstMetaInfo that can be used to access metadata.
*/
const GstBufferMetaInfo *
gst_buffer_meta_register_info (const GstBufferMetaInfo * info)
const GstMetaInfo *
gst_meta_register (const gchar * api, const gchar * impl, gsize size,
GstMetaInitFunction init_func, GstMetaFreeFunction free_func,
GstMetaCopyFunction copy_func, GstMetaSubFunction sub_func,
GstMetaSerializeFunction serialize_func,
GstMetaDeserializeFunction deserialize_func)
{
g_return_val_if_fail (info != NULL, NULL);
g_return_val_if_fail (info->name != NULL, NULL);
g_return_val_if_fail (info->size != 0, NULL);
GstMetaInfo *info;
g_return_val_if_fail (api != NULL, NULL);
g_return_val_if_fail (impl != NULL, NULL);
g_return_val_if_fail (size != 0, NULL);
info = g_slice_new (GstMetaInfo);
info->api = g_quark_from_string (api);
info->impl = g_quark_from_string (impl);
info->size = size;
info->init_func = init_func;
info->free_func = free_func;
info->copy_func = copy_func;
info->sub_func = sub_func;
info->serialize_func = serialize_func;
info->deserialize_func = deserialize_func;
GST_DEBUG ("register \"%s\" of size %" G_GSIZE_FORMAT, info->name,
info->size);
GST_DEBUG ("register \"%s\" implementing \"%s\" of size %" G_GSIZE_FORMAT,
api, impl, size);
g_static_rw_lock_writer_lock (&lock);
g_hash_table_insert (metainfo, (gpointer) info->name, (gpointer) info);
g_hash_table_insert (metainfo, (gpointer) impl, (gpointer) info);
g_static_rw_lock_writer_unlock (&lock);
return info;
}
/**
* gst_buffer_meta_get_info:
* gst_meta_get_info:
* @name: the name
*
* Lookup a previously registered meta info structure by its @name.
* Lookup a previously registered meta info structure by its @implementor name.
*
* Returns: a #GstBufferMetaInfo with @name or #NULL when no such metainfo
* Returns: a #GstMetaInfo with @name or #NULL when no such metainfo
* exists.
*/
const GstBufferMetaInfo *
gst_buffer_meta_get_info (const gchar * name)
const GstMetaInfo *
gst_meta_get_info (const gchar * impl)
{
GstBufferMetaInfo *info;
GstMetaInfo *info;
g_return_val_if_fail (name != NULL, NULL);
g_return_val_if_fail (impl != NULL, NULL);
g_static_rw_lock_reader_lock (&lock);
info = g_hash_table_lookup (metainfo, name);
info = g_hash_table_lookup (metainfo, impl);
g_static_rw_lock_reader_unlock (&lock);
return info;
......
/* GStreamer
* Copyright (C) 2009 Wim Taymans <wim.taymans@gmail.be>
*
* gstbuffermeta.h: Header for Buffer Metadata structures
* gstmeta.h: Header for Metadata structures
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
......@@ -20,31 +20,31 @@
*/
#ifndef __GST_BUFFER_META_H__
#define __GST_BUFFER_META_H__
#ifndef __GST_META_H__
#define __GST_META_H__
G_BEGIN_DECLS
typedef struct _GstBufferMeta GstBufferMeta;
typedef struct _GstBufferMetaInfo GstBufferMetaInfo;
typedef struct _GstMeta GstMeta;
typedef struct _GstMetaInfo GstMetaInfo;
/**
* GstBufferMeta:
* @info: pointer to the #GstBufferMetaInfo
* GstMeta:
* @info: pointer to the #GstMetaInfo
*
* Base structure for buffer metadata. Custom metadata will put this structure
* Base structure for metadata. Custom metadata will put this structure
* as the first member of their structure.
*/
struct _GstBufferMeta {
const GstBufferMetaInfo *info;
struct _GstMeta {
const GstMetaInfo *info;
};
/**
* GST_BUFFER_META_TRACE_NAME:
* GST_META_TRACE_NAME:
*
* The name used for tracing memory allocations.
*/
#define GST_BUFFER_META_TRACE_NAME "GstBufferMeta"
#define GST_META_TRACE_NAME "GstMeta"
/**
* GstMetaInitFunction:
......@@ -53,7 +53,7 @@ struct _GstBufferMeta {
*
* Function called when @meta is initialized in @buffer.
*/
typedef void (*GstMetaInitFunction) (GstBufferMeta *meta, GstBuffer *buffer);
typedef void (*GstMetaInitFunction) (GstMeta *meta, GstBuffer *buffer);
/**
* GstMetaFreeFunction:
......@@ -62,7 +62,7 @@ typedef void (*GstMetaInitFunction) (GstBufferMeta *meta, GstBuffer *buffer)
*
* Function called when @meta is freed in @buffer.
*/
typedef void (*GstMetaFreeFunction) (GstBufferMeta *meta, GstBuffer *buffer);
typedef void (*GstMetaFreeFunction) (GstMeta *meta, GstBuffer *buffer);
/**
* GstMetaCopyFunction:
......@@ -73,7 +73,7 @@ typedef void (*GstMetaFreeFunction) (GstBufferMeta *meta, GstBuffer *buffer)
* Function called when a copy of @buffer is made and @meta should be copied to
* @copy.
*/
typedef void (*GstMetaCopyFunction) (GstBuffer *copy, GstBufferMeta *meta,
typedef void (*GstMetaCopyFunction) (GstBuffer *copy, GstMeta *meta,
const GstBuffer *buffer);
/**
* GstMetaSubFunction:
......@@ -87,25 +87,26 @@ typedef void (*GstMetaCopyFunction) (GstBuffer *copy, GstBufferMeta *meta,
* subbuffer @subbuf from @buffer at @offset and with @size. An
* implementation could decide to copy and update the metadata on @subbuf.
*/
typedef void (*GstMetaSubFunction) (GstBuffer *subbuf, GstBufferMeta *meta,
typedef void (*GstMetaSubFunction) (GstBuffer *subbuf, GstMeta *meta,
GstBuffer *buffer, guint offset, guint size);
/**
* GstMetaSerializeFunction:
* @meta: a #GstMeta
*/
typedef gchar * (*GstMetaSerializeFunction) (GstBufferMeta *meta);
typedef gchar * (*GstMetaSerializeFunction) (GstMeta *meta);
/**
* GstMetaDeserializeFunction:
* @meta: a #GstMeta
*/
typedef gboolean (*GstMetaDeserializeFunction) (GstBufferMeta *meta,
typedef gboolean (*GstMetaDeserializeFunction) (GstMeta *meta,
const gchar *s);
/**
* GstBufferMetaInfo:
* @name: tag indentifying the metadata
* GstMetaInfo:
* @api: tag indentifying the metadata structure and api
* @impl: tag indentifying the implementor of the api
* @size: size of the metadata
* @init_func: function for initializing the metadata
* @free_func: function for freeing the metadata
......@@ -114,11 +115,12 @@ typedef gboolean (*GstMetaDeserializeFunction) (GstBufferMeta *meta,
* @serialize_func: function for serializing
* @deserialize_func: function for deserializing
*
* The #GstBufferMetaInfo provides information about a specific metadata
* The #GstMetaInfo provides information about a specific metadata
* structure.
*/
struct _GstBufferMetaInfo {
const gchar *name;
struct _GstMetaInfo {
GQuark api;
GQuark impl;
gsize size;
GstMetaInitFunction init_func;
......@@ -129,11 +131,18 @@ struct _GstBufferMetaInfo {
GstMetaDeserializeFunction deserialize_func;
};
void _gst_buffer_meta_init (void);
void _gst_meta_init (void);
const GstBufferMetaInfo * gst_buffer_meta_register_info (const GstBufferMetaInfo *info);
const GstBufferMetaInfo * gst_buffer_meta_get_info (const gchar * name);
const GstMetaInfo * gst_meta_register (const gchar *api, const gchar *impl,
gsize size,
GstMetaInitFunction init_func,
GstMetaFreeFunction free_func,
GstMetaCopyFunction copy_func,
GstMetaSubFunction sub_func,
GstMetaSerializeFunction serialize_func,
GstMetaDeserializeFunction deserialize_func);
const GstMetaInfo * gst_meta_get_info (const gchar * impl);
G_END_DECLS
#endif /* __GST_BUFFER_META_H__ */
#endif /* __GST_META_H__ */
......@@ -100,7 +100,7 @@ check_PROGRAMS = \
$(ABI_CHECKS) \
gst/gstbuffer \
gst/gstbufferlist \
gst/gstbuffermeta \
gst/gstmeta \
gst/gstbus \
gst/gstcaps \
$(CXX_CHECKS) \
......