From: Richard Boulton Date: Sun, 18 Mar 2001 03:57:59 +0000 (+0000) Subject: Various updates to PWG; mainly adding information about types and properties. X-Git-Tag: BRANCH-INCSCHED1-200104161-ROOT~47 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=d5c2bc5f985545697930f1d220a5556eba281a0b;p=platform%2Fupstream%2Fgstreamer.git Various updates to PWG; mainly adding information about types and properties. Original commit message from CVS: Various updates to PWG; mainly adding information about types and properties. Removed concepts.sgml and typesnprops.sgml; merged into main file. I was finding that having all the separate subfiles simply stopped me from finding what I wanted to edit. Maybe I'll split it up again later, but this is much better for now. --- diff --git a/docs/fwg/Makefile.am b/docs/fwg/Makefile.am index bd4be9b..1c18923 100644 --- a/docs/fwg/Makefile.am +++ b/docs/fwg/Makefile.am @@ -4,11 +4,9 @@ htmlname = index.html sgml_files = gst-plugin-writers-guide.sgml \ titlepage.sgml \ intro.sgml \ - concepts.sgml \ firstplugin.sgml \ testapp.sgml \ - loopbased.sgml \ - typesnprops.sgml + loopbased.sgml fig_files = eps_files = diff --git a/docs/fwg/concepts.sgml b/docs/fwg/concepts.sgml deleted file mode 100644 index af4181b..0000000 --- a/docs/fwg/concepts.sgml +++ /dev/null @@ -1,85 +0,0 @@ - - Plugins - - Extensions to &GStreamer; can be made using a plugin mechanism. This is - used extensively in &GStreamer; even if only the standard package is - being used: a few very basic functions reside in the core library, and - all others are in a standard set of plugins. - - - Plugins can extend GStreamer in several - - - Plugins are only loaded when needed: a plugin registry is used to - store the details of the plugins so that it is not neccessary to load - all plugins to determine which are needed. - This registry needs to be updated when a new plugin is added to the - system: see the gstreamer-register utility and the - documentation in the GStreamer Application Development - Manual for more details. - - - User extensions to &GStreamer; can be installed in the main plugin - directory, and will immediately be available for use in applications. - gstreamer-register should be run to update - the repository: but the system should work correctly even if it hasn't - been - it will just take longer to load the correct plugin. - - - User specific plugin directories and registries will be available in future - versions of &GStreamer;. - - - - - Elements - - Elements are at the core of &GStreamer;. Without elements, &GStreamer; is - just a bunch of pipe fittings with nothing to connect. A large number of - elements (filters, sources and sinks) ship with &GStreamer;, but extra - elements can also be written. - - - An element may be constructed in several different ways, but all must - conform to the same basic rules. A simple filter may be built with the - FilterFactory, where the only code that need be written is the actual - filter code. A more complex filter, or a source or sink, will need to be - written out fully for complete access to the features and performance - possible with &GStreamer;. - - - The implementation of a new element will be contained in a plugin: - a single plugin may contain the implementation of several elements, or - just a single one. - - - - - Buffers - - - - - - Scheduling - - - - - - Chain vs Loop Elements - - - - - - Typing and Properties - - - - - - Metadata - - - diff --git a/docs/fwg/gst-plugin-writers-guide.sgml b/docs/fwg/gst-plugin-writers-guide.sgml index f156fae..3ffe4e3 100644 --- a/docs/fwg/gst-plugin-writers-guide.sgml +++ b/docs/fwg/gst-plugin-writers-guide.sgml @@ -3,16 +3,12 @@ - - - - @@ -62,11 +58,109 @@ This section introduces the basic concepts required to understand the issues involved in extending &GStreamer; + + + Many of these concepts are explained in greater detail in the + GStreamer Application Development Manual, and are merely mentioned + here to refresh your memory. - &CONCEPTS; + + + Plugins + + Extensions to &GStreamer; can be made using a plugin mechanism. This is + used extensively in &GStreamer; even if only the standard package is + being used: a few very basic functions reside in the core library, and + all others are implemented in plugins. + + + Plugins are only loaded when needed: a plugin registry is used to + store the details of the plugins so that it is not neccessary to load + all plugins to determine which are needed. + This registry needs to be updated whenever a new plugin is added to the + system: see the gstreamer-register utility and the + documentation in the GStreamer Application Development + Manual for more details. + + + User extensions to &GStreamer; can be installed in the main plugin + directory, and will immediately be available for use in applications. + gstreamer-register should be run to update + the repository: but the system should work correctly even if it hasn't + been - it will just take longer to load the correct plugin. + + + User specific plugin directories and registries will be available + in future versions of &GStreamer. + + + + + Elements + + Elements are at the core of &GStreamer;. Without elements, &GStreamer; + is just + a bunch of pipe fittings with nothing to connect. A large number of + elements (filters, sources and sinks) ship with &GStreamer;, but extra + elements can also be written. + + + An element may be constructed in several different ways, but all must + conform to the same basic rules. A simple filter may be built with the + FilterFactory, where the only code that need be written is the actual + filter code. A more complex filter, or a source or sink, will need to be + written out fully for complete access to the features and performance + possible with &GStreamer;. + + + The implementation of a new element will be contained in a plugin: + a single plugin may contain the implementation of several elements, or + just a single one. + + + + + Buffers + + Buffers are structures used to pass data between elements. All streams + of data are chopped up into chunks which are stored in buffers. + Buffers can be of any size, and also contain metadata indicating the + type of data contained in them. + + + + + Typing and Properties + + A type system is used to ensure that the data passed between elements + is in a recognised format, and that the various parameters required + to fully specify that format match up correctly. Each connection + that is made between elements has a specified type. This is related, + but different, to the metadata in buffers which describes the type + of data in that particular buffer. + + + + + Metadata + + + + + + Scheduling + + + + + + Chain vs Loop Elements + + + @@ -119,10 +213,149 @@ Types and Properties + There is a very large set of possible types that may be used to + pass data between elements. Indeed, each new element that is defined + may use a new data format (though unless at least one other element + recognises that format, it will be most likely be useless since + nothing will be able to link with it). + + + In order for types to be useful, and for systems like autopluggers to + work, it is neccessary that all elements + agree on the type definitions, and which properties are required + for each type. The GStreamer framework itself + simply provides the ability to define types and parameters, but does + not fix the meaning of types and parameters, and does not enforce + standards on the creation of new types. This is a matter for + a policy to decide, not technical systems to enforce. + + + For now, the policy is simple: + + + + Do not create a new type if you could use one which already + exists. + + + + + If creating a new type, discuss it first with the other + GStreamer developers, on at least one of: IRC, mailing lists, + the GStreamer wiki. + + + + + Try to ensure that the name for a new format is as unlikely to + conflict with anything else created already, and is not a more + generalised name than it should be. For example: + "audio/compressed" would be too generalised a name to represent + audio data compressed with an mp3 codec. Instead "audio/mp3" + might be an appropriate name, or "audio/compressed" could exist + and have a property indicating the type of compression used. + + + + + Ensure that, when you do create a new type, you specify it + clearly, and get it added to the list of known types so that + other developers can use the type correctly when writing their + elements. + + + - &TYPESNPROPS; + + The basic types + + This is a list of the basic types used for buffers. For each type, we + give the name ("mime type") of the type, the list of properties which + are associated with the type, the meaning of each property, and the + purpose of the type. + + + + + audio/raw + - Unstructured and uncompressed raw audio data. + + law + - The law used to describe the data. This is an integer for which + there are three valid values: 0 for linear, 1 for + mu law, 2 for A law. + + endianness + - The order of bytes in a sample. This is an integer for + which there are two valid values: 0 for little-endian (ie, bytes + are least significant first), 1 for big-endian (ie, most + significant byte first). + + signed + - Whether the samples are signed or not. This is an integer + for which there are two valid values: 0 for unsigned, 1 for + signed. + + width + - The number of bits per sample. This is extremely likely to be + a multiple of 8, but as ever this is up to each element supporting + this format to specify. + + depth + - The number of bits used per sample. This must be less than or + equal to the width: if less than the width, the low bits are + assumed to be the ones used. For example, width=32, depth=24 + means that each sample is stored in a 32 bit word, but only the + low 24 bits are actually used. + + rate + - The sample rate of the data, in samples per second. + + channels + - The number of channels of audio data. + + + For example: 16 bit, unsigned, linear, monophonic, big-endian, + 44100KHz audio would be represented by + "law=0,endianness=1,signed=0,width=16,depth=16,rate=44100,channels=1" + + + + + + + audio/mp3 + + + + + + + Building a simple format for testing + + + + + + A simple MIME type + + + + + + Type properties + + + + + + Typefind functions and autoplugging + + + + diff --git a/docs/fwg/typesnprops.sgml b/docs/fwg/typesnprops.sgml deleted file mode 100644 index acb30ac..0000000 --- a/docs/fwg/typesnprops.sgml +++ /dev/null @@ -1,24 +0,0 @@ - - Building a simple format for testing - - - - - - A simple MIME type - - - - - - Type properties - - - - - - Typefind functions and autoplugging - - - -