diff --git a/ChangeLog b/ChangeLog index 8671fc0269..e461920d3e 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,15 @@ +2004-01-26 Ronald Bultje + + * docs/pwg/advanced_types.xml: + * docs/pwg/intro_basics.xml: + * docs/pwg/intro_preface.xml: + * docs/pwg/pwg.xml: + * docs/pwg/titlepage.xml: + First try to resurrect the PWG. I'm halfway integrating the mimetypes + in here (docs/random/mimetypes), and will from there on work on both + updating outdated parts and adding missing parts. + That doesn't mean I'll fix it completely, but I'll try at least. ;). + 2004-01-26 Thomas Vander Stichele * gst/gsterror.h: reinstate GST_LIBRARY_ERROR_ENCODE until diff --git a/docs/pwg/advanced-types.xml b/docs/pwg/advanced-types.xml index 62ed2cf1aa..914ed9899e 100644 --- a/docs/pwg/advanced-types.xml +++ b/docs/pwg/advanced-types.xml @@ -85,4 +85,583 @@ + + + + + List of Defined Types + + Below is a list of all the defined types in &GStreamer;. They are split + up in separate tables for audio, video, container, text and other + types, for the sake of readability. Below each table might follow a + list of notes that apply to that table. In the definition of each type, + we try to follow the types and rules as defined by + IANA for as far as possible. + + + Note that many of the properties are not required, + but rather optional properties. This means that + most of these properties can be extracted from the container header, + but that - in case the container header does not provide these - they + can also be extracted by parsing the stream header or the stream + content. The policy is that your element should provide the data that + it knows about by only parsing its own content, not another element's + content. Example: the AVI header provides samplerate of the contained + audio stream in the header. MPEG system streams don't. This means that + an AVI stream demuxer would provide samplerate as a property for MPEG + audio streams, whereas an MPEG demuxer would not. + + + + Table of Audio Types + + + + + + + + Mime Type + Description + Property + Property Type + Property Values + Property Description + + + + + + + + + + All audio types. + + + + + + + audio/* + + All audio types + + rate + integer + greater than 0 + + The sample rate of the data, in samples (per channel) per second. + + + + channels + integer + greater than 0 + + The number of channels of audio data. + + + + + + + + All raw audio types. + + + + + + + audio/x-raw-int + + Unstructured and uncompressed raw fixed-integer audio data. + + endianness + integer + G_BIG_ENDIAN (1234) or G_LITTLE_ENDIAN (4321) + + The order of bytes in a sample. The value G_LITTLE_ENDIAN (4321) + means little-endian (byte-order is least + significant byte first). The value G_BIG_ENDIAN (1234) + means big-endian (byte order is most + significant byte first). + + + + signed + boolean + TRUE or FALSE + + Whether the values of the integer samples are signed or not. + Signed samples use one bit to indicate sign (negative or + positive) of the value. Unsigned samples are always positive. + + + + width + integer + greater than 0 + + Number of bits allocated per sample. + + + + depth + integer + greater than 0 + + The number of bits used per sample. This must be less than or + equal to the width: If the depth is less than the width, the + low bits are assumed to be the ones used. For example, a width + of 32 and a depth of 24 means that each sample is stored in a + 32 bit word, but only the low 24 bits are actually used. + + + + + + + audio/x-raw-float + + Unstructured and uncompressed raw floating-point audio data. + + endianness + integer + G_BIG_ENDIAN (1234) or G_LITTLE_ENDIAN (4321) + + The order of bytes in a sample. The value G_LITTLE_ENDIAN (4321) + means little-endian (byte-order is least + significant byte first). The value G_BIG_ENDIAN (1234) + means big-endian (byte order is most + significant byte first). + + + + width + integer + greater than 0 + + The amount of bits used and allocated per sample. + + + + buffer-frames + integer + greater than 0 + + The number of frames per buffer. The reason for this property + is that the element does not need to reuse buffers or use data + spanned over multiple buffers, so this property - when used + rightly - will decrease latency. Note that some people think that + this property is very ugly, whereas others think it is vital for + the use of &GStreamer; in professional audio applications. + + + + + + + + All encoded audio types. + + + + + + + audio/x-ac3 + AC-3 or A52 audio streams. + + + + + There are currently no specific properties defined or needed for + this type. + + + + + + + audio/x-adpcm + ADPCM Audio streams. + layout + string + + quicktime, wav, + microsoft or 4xm. + + + The layout defines the packing of the samples in the stream. In + ADPCM, most formats store multiple samples per channel together. + This number of samples differs per format, hence the different + layouts. On the long term, we probably want this variable to die + and use something more descriptive, but this will do for now. + + + + + + + audio/x-dv + Audio as provided in a Digital Video stream. + + + + + There are currently no specific properties defined or needed for + this type. + + + + + + + audio/x-flac + Free Lossless Audio codec (FLAC). + + + + + There are currently no specific properties defined or needed for + this type. + + + + + + + audio/x-gsm + Data encoded by the GSM codec. + + + + + There are currently no specific properties defined or needed for + this type. + + + + + + + audio/x-alaw + A-Law Audio. + + + + + There are currently no specific properties defined or needed for + this type. + + + + + + + audio/x-mulaw + Mu-Law Audio. + + + + + There are currently no specific properties defined or needed for + this type. + + + + + + + audio/x-mace + MACE Audio (used in Quicktime). + maceversion + integer + 3 or 6 + + The version of the MACE audio codec used to encode the stream. + + + + + + + audio/mpeg + + Audio data compressed using the MPEG audio encoding scehem. + + mpegversion + integer + 1, 2 or 4 + + The MPEG-version used for encoding the data. The value 1 refers + to MPEG-1, -2 and -2.5 layer 1, 2 or 3. The values 2 and 4 refer + to the MPEG-AAC audio encoding schemes. + + + + framed + boolean + 0 or 1 + + A true value indicates that each buffer contains exactly one + frame. A false value indicates that frames and buffers do not + necessarily match up. + + + + layer + integer + 1, 2, or 3 + + The compression scheme layer used to compress the data + (only if mpegversion=1). + + + + bitrate + integer + greater than 0 + + The bitrate, in bits per second. For VBR (variable bitrate) + MPEG data, this is the average bitrate. + + + + + + + audio/x-pn-realaudio + Real Audio data. + raversion + integer + 1 or 2 + + The version of the Real Audio codec used to encode the stream. + 1 stands for a 14k4 stream, 2 stands for a 28k8 stream. + + + + + + + audio/x-qdm2 + Data encoded by the QDM version 2 codec. + + + + + There are currently no specific properties defined or needed for + this type. + + + + + + + audio/x-speex + Data encoded by the Speex audio codec + + + + + There are currently no specific properties defined or needed for + this type. + + + + + + + audio/x-vorbis + Vorbis audio data. + + + + + There are currently no specific properties defined or needed for + this type. + + + + + + + audio/x-wma + Windows Media Audio + wmaversion + integer + 1 or 2 + + The version of the WMA codec used to encode the stream. + + + + +
+ + + Table of Video Types + + + + + + + + Mime Type + Description + Property + Property Type + Property Values + Property Description + + + + + + + + + + All video types. + + + + + + + video/* + + All video types + + width + integer + greater than 0 + The width of the video image + + + height + integer + greater than 0 + The height of the video image + + + framerate + double + greater than 0 + + The (average) framerate in frames per second. Note that this + property does not guarantee in any way that + it will actually come close to this value. If you need a fixed + framerate, please use an element that provides that (such as + videodrop). + + + + + + + + All raw video types. + + + + + + + video/x-raw-yuv + YUV (or Y'Cb'Cr) video format. + format + fourcc + + YUY2, YVYU, UYVY, Y41P, IYU2, Y42B, YV12, I420, Y41B, YUV9, YVU9, + Y800 + + + The layout of the video. See FourCC definition site + for references and definitions. YUY2, YVYU and UYVY are 4:2:2 + packed-pixel, Y41P is 4:1:1 packed-pixel and IYU2 is 4:4:4 + packed-pixel. Y42B is 4:2:2 planar, YV12 and I420 are 4:2:0 + planar, Y41B is 4:1:1 planar and YUV9 and YVU9 are 4:1:0 planar. + Y800 contains Y-samples only (black/white). + + + + + video/x-raw-rgb + Red-Green-Blue (RBG) video. + bpp + integer + greater than 0 + + The number of bits allocated per pixel. This is usually 16, 24 + or 32. + + + + + depth + integer + greater than 0 + + The number of bits used per pixel by the R/G/B components. This + is usually 15, 16 or 24. + + + + + endianness + integer + G_BIG_ENDIAN (1234) or G_LITTLE_ENDIAN (4321) + + The order of bytes in a sample. The value G_LITTLE_ENDIAN (4321) + means little-endian (byte-order is least + significant byte first). The value G_BIG_ENDIAN (1234) + means big-endian (byte order is most + significant byte first). For 24/32bpp, this should always + be big endian because the byte order can be given in both. + + + + + red_mask, green_mask and blue_mask + integer + any + + The masks that cover all the bits used by each of the samples. + The mask should be given in the endianness specified above. This + means that for 24/32bpp, the masks might be opposite to host byte + order (if you are working on little-endian computers). + + + + + + + + All encoded video types. + + + + + + + video/x-divx + DivX video. + divxversion + integer + 3, 4 or 5 + + Version of the DivX codec used to encode the stream. + + + + +
+ diff --git a/docs/pwg/intro-basics.xml b/docs/pwg/intro-basics.xml index 43f9efd770..d6ec4a6bb3 100644 --- a/docs/pwg/intro-basics.xml +++ b/docs/pwg/intro-basics.xml @@ -103,16 +103,41 @@ - - Buffers + + Data, Buffers and Events All streams of data in &GStreamer; are chopped up into chunks that are passed from a source pad on one element to a sink pad on another element. - Buffers are structures used to hold these chunks of - data. Buffers can be of any size, theoretically, and they may contain any - sort of data that the two linked pads know how to handle. Normally, a - buffer contains a chunk of some sort of audio or video data that flows - from one element to another. + Data are structures used to hold these chunks of + data. + + + Data contains the following important types: + + + + An exact type indicating what type of data (control, content, ...) + this Data is. + + + + + A reference count indicating the number of elements currently + holding a reference to the buffer. When the buffer reference count + falls to zero, the buffer will be unlinked, and its memory will be + freed in some sense (see below for more details). + + + + + + There are two types of data defined: events (control) and buffers + (content). + + + Buffers may contain any sort of data that the two linked pads + know how to handle. Normally, a buffer contains a chunk of some sort of + audio or video data that flows from one element to another. Buffers also contain metadata describing the buffer's contents. Some of @@ -130,16 +155,31 @@ - A GstData object describing the type of the - buffer's data. + A timestamp indicating the preferred display timestamp of the + content in the buffer. + + + + + + Events + contain information on the state of the stream flowing between the two + linked pads. Events will only be sent if the element explicitely supports + them, else the core will (try to) handle the events automatically. Events + are used to indicate, for example, a clock discontinuity, the end of a + media stream or that the cache should be flushed. + + + Events may contain several of the following items: + + + + A subtype indicating the type of the contained event. - A reference count indicating the number of elements currently - holding a reference to the buffer. When the buffer reference count - falls to zero, the buffer will be unlinked, and its memory will be - freed in some sense (see below for more details). + The other contents of the event depend on the specific event type. @@ -147,7 +187,9 @@ See the &GstLibRef; for the current implementation details of a GstBuffer. + url="../gstreamer/gstreamer-gstdata.html">GstData, GstBuffer and GstEvent. - Types and Properties + Mimetypes and Properties &GStreamer; uses a type system to ensure that the data passed between - elements is in a recognized format. The type system is also important for - ensuring that the parameters required to fully specify a format match up - correctly when linking pads between elements. Each link that is - made between elements has a specified type. + elements is in a recognized format. The type system is also important + for ensuring that the parameters required to fully specify a format match + up correctly when linking pads between elements. Each link that is + made between elements has a specified type and optionally a set of + properties. @@ -201,9 +247,11 @@ The Basic Types &GStreamer; already supports many basic media types. Following is a - table of the basic types used for buffers in &GStreamer;. The table - contains the name ("mime type") and a description of the type, the - properties associated with the type, and the meaning of each property. + table of a few of the the basic types used for buffers in + &GStreamer;. The table contains the name ("mime type") and a + description of the type, the properties associated with the type, and + the meaning of each property. A full list of supported types is + included in . @@ -226,15 +274,15 @@ - audio/raw - - Unstructured and uncompressed raw audio data. + audio/* + + All audio types rate integer greater than 0 - The sample rate of the data, in samples per second. + The sample rate of the data, in samples (per channel) per second. @@ -245,43 +293,33 @@ The number of channels of audio data. + + + - format - string - int or float - - The format in which the audio data is passed. + audio/x-raw-int + + Unstructured and uncompressed raw integer audio data. - - - law - integer - 0, 1, or 2 - - (Valid only if the data is in integer format.) The law used to - describe the data. The value 0 indicates linear, 1 - indicates mu law, and 2 indicates - A law. - - - endianness - boolean - 0 or 1 + integer + G_BIG_ENDIAN (1234) or G_LITTLE_ENDIAN (4321) - (Valid only if the data is in integer format.) The order of bytes - in a sample. The value 0 means little-endian (bytes - are least significant first). The value 1 means - big-endian (most significant byte first). + The order of bytes in a sample. The value G_LITTLE_ENDIAN (4321) + means little-endian (byte-order is least + significant byte first). The value G_BIG_ENDIAN (1234) + means big-endian (byte order is most + significant byte first). signed boolean - 0 or 1 + TRUE or FALSE - (Valid only if the data is in integer format.) Whether the samples - are signed or not. + Whether the values of the integer samples are signed or not. + Signed samples use one bit to indicate sign (negative or + positive) of the value. Unsigned samples are always positive. @@ -289,8 +327,7 @@ integer greater than 0 - (Valid only if the data is in integer format.) The number of bits - per sample. + Number of bits allocated per sample. @@ -298,54 +335,31 @@ integer greater than 0 - (Valid only if the data is in integer format.) The number of bits - used per sample. This must be less than or equal to the width: If - the depth is less than the width, the low bits are assumed to be - the ones used. For example, a width of 32 and a depth of 24 means - that each sample is stored in a 32 bit word, but only the low 24 - bits are actually used. - - - - layout - string - gfloat - - (Valid only if the data is in float format.) A string representing - the way in which the floating point data is represented. - - - - intercept - float - any, normally 0 - - (Valid only if the data is in float format.) A floating point - value representing the value that the signal - centers on. - - - - slope - float - any, normally 1.0 - - (Valid only if the data is in float format.) A floating point - value representing how far the signal deviates from the intercept. - A slope of 1.0 and an intercept of 0.0 would mean an audio signal - with minimum and maximum values of -1.0 and 1.0. A slope of - 0.5 and intercept of 0.5 would represent values in the range 0.0 - to 1.0. + The number of bits used per sample. This must be less than or + equal to the width: If the depth is less than the width, the + low bits are assumed to be the ones used. For example, a width + of 32 and a depth of 24 means that each sample is stored in a + 32 bit word, but only the low 24 bits are actually used. - audio/mp3 - - Audio data compressed using the mp3 encoding scheme. + audio/mpeg + + Audio data compressed using the MPEG audio encoding scheme. + mpegversion + integer + 1, 2 or 4 + + The MPEG-version used for encoding the data. The value 1 refers + to MPEG-1, -2 and -2.5 layer 1, 2 or 3. The values 2 and 4 refer + to the MPEG-AAC audio encoding schemes. + + + framed boolean 0 or 1 @@ -360,7 +374,8 @@ integer 1, 2, or 3 - The compression scheme layer used to compress the data. + The compression scheme layer used to compress the data + (only if mpegversion=1). @@ -368,134 +383,26 @@ integer greater than 0 - The bitrate, in kilobits per second. For VBR (variable bitrate) - mp3 data, this is the average bitrate. - - - - channels - integer - greater than 0 - - The number of channels of audio data present. - - - - joint-stereo - boolean - 0 or 1 - - If true, this implies that stereo data is stored as a combined - signal and the difference between the signals, rather than as two - entirely separate signals. If true, the channels - attribute must not be zero. + The bitrate, in bits per second. For VBR (variable bitrate) + MPEG data, this is the average bitrate. - audio/x-ogg - - Audio data compressed using the Ogg Vorbis encoding scheme. - + audio/x-vorbis + Vorbis audio data - FIXME: There are currently no parameters defined for this type. + There are currently no specific properties defined for this type. - - - - - video/raw - - Raw video data. - - fourcc - FOURCC code - - - A FOURCC code identifying the format in which this data is stored. - FOURCC (Four Character Code) is a simple system to allow - unambiguous identification of a video datastream format. See - http://www.webartz.com/fourcc/ - - - - width - integer - greater than 0 - - The number of pixels wide that each video frame is. - - - - height - integer - greater than 0 - - The number of pixels high that each video frame is. - - - - - - - video/mpeg - - Video data compressed using an MPEG encoding scheme. - - - - - - FIXME: There are currently no parameters defined for this type. - - - - - - - video/x-msvideo - - Video data compressed using the AVI encoding scheme. - - - - - - FIXME: There are currently no parameters defined for this type. - - -
- - - - - Events - - Sometimes elements in a media processing pipeline need to know that - something has happened. An event is a special type of - data in &GStreamer; designed to serve this purpose. Events describe some - sort of activity that has happened somewhere in an element's pipeline, for - example, the end of the media stream or a clock discontinuity. Just like - any other data type, an event comes to an element on a sink pad and is - contained in a normal buffer. Unlike normal stream buffers, though, an - event buffer contains only an event, not any media stream data. - - - See the &GstLibRef; for the current implementation details of a GstEvent. - - diff --git a/docs/pwg/intro-preface.xml b/docs/pwg/intro-preface.xml index 1713e754d5..f2463354b7 100644 --- a/docs/pwg/intro-preface.xml +++ b/docs/pwg/intro-preface.xml @@ -170,11 +170,10 @@ The remainder of this introductory part of the guide presents a short overview of the basic concepts involved in &GStreamer; plugin development. Topics covered include , , , - , and . If you are already familiar with this - information, you can use this short overview to refresh your memory, or - you can skip to . + linkend="sect1-basics-pads"/>, and + . If you are already familiar with + this information, you can use this short overview to refresh your memory, + or you can skip to . As you can see, there a lot to learn, so let's get started! diff --git a/docs/pwg/pwg.xml b/docs/pwg/pwg.xml index be67573c6c..6cf0f98434 100644 --- a/docs/pwg/pwg.xml +++ b/docs/pwg/pwg.xml @@ -33,7 +33,7 @@ GStreamer"> - + GStreamer Application Development Manual"> GStreamer Library Reference"> ]> diff --git a/docs/pwg/titlepage.xml b/docs/pwg/titlepage.xml index e4a58e2450..6aa6a3203c 100644 --- a/docs/pwg/titlepage.xml +++ b/docs/pwg/titlepage.xml @@ -41,6 +41,17 @@ + + + Ronald + S. + Bultje + + + rbultje@ronald.bitfreak.net + + +