diff --git a/docs/pwg/intro-basics.xml b/docs/pwg/intro-basics.xml index 9b05369e20..4a50e91d0c 100644 --- a/docs/pwg/intro-basics.xml +++ b/docs/pwg/intro-basics.xml @@ -39,7 +39,7 @@ processes a stream of data. Producers and consumers of data are called source and sink elements, respectively. Bin elements contain other elements. - One type of bin is responsible for scheduling the elements that they + One type of bin is responsible for synchronization of the elements that they contain so that data flows smoothly. Another type of bin, called autoplugger elements, automatically add other elements to the bin and links them together so that they act as a @@ -49,10 +49,10 @@ The plugin mechanism is used everywhere in &GStreamer;, even if only the standard packages are being used. A few very basic functions reside in the core library, and all others are implemented in plugins. A plugin registry - is used to store the details of the plugins in an XML file. This way, a - program using &GStreamer; does not have to load all plugins to determine - which are needed. Plugins are only loaded when their provided elements are - requested. + is used to store the details of the plugins in an binary registry file. + This way, a program using &GStreamer; does not have to load all plugins to + determine which are needed. Plugins are only loaded when their provided + elements are requested. See the &GstLibRef; for the current implementation details of - Data, Buffers and Events + GstMiniObject, 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. - Data are structures used to hold these chunks of - data. + GstMiniObject is the structure used to hold these + chunks of data. - Data contains the following important types: + GstMiniObject contains the following important types: - An exact type indicating what type of data (control, content, ...) - this Data is. + An exact type indicating what type of data (event, buffer, ...) + this GstMiniObject 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 + holding a reference to the miniobject. When the reference count + falls to zero, the miniobject will be disposed, 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). + For data transport, there are two types of GstMiniObject defined: + events (control) and buffers (content). Buffers may contain any sort of data that the two linked pads @@ -146,12 +146,8 @@ - A pointer to the buffer's data. - - - - - An integer indicating the size of the buffer's data. + Pointers to one or more GstMemory objects. GstMemory objects are + refcounted objects that encapsulate a region of memory. @@ -167,7 +163,7 @@ contain information on the state of the stream flowing between the two linked pads. Events will only be sent if the element explicitly 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 + are used to indicate, for example, a media type, the end of a media stream or that the cache should be flushed. @@ -220,21 +216,16 @@ Another way an element might get specialized buffers is to - request them from a downstream peer. These are called - downstream-allocated buffers. Elements can ask a - peer connected to a source pad to create an empty buffer of - a given size. If a downstream element is able to create a - special buffer of the correct size, it will do so. Otherwise - &GStreamer; will automatically create a generic buffer instead. - The element that requested the buffer can then copy data into - the buffer, and push the buffer to the source pad it was - allocated from. + request them from a downstream peer through a GstBufferPool or + GstAllocator. Elements can ask a GstBufferPool or GstAllocator + from the downstream peer element. If downstream is able to provide + these objects, upstream can use them to allocate buffers. Many sink elements have accelerated methods for copying data to hardware, or have direct access to hardware. It is common - for these elements to be able to create downstream-allocated - buffers for their upstream peers. One such example is + for these elements to be able to create a GstBufferPool or + GstAllocator for their upstream peers. One such example is ximagesink. It creates buffers that contain XImages. Thus, when an upstream peer copies data into the buffer, it is copying directly into the XImage, enabling ximagesink to draw the @@ -256,7 +247,7 @@ - Mimetypes and Properties + Media types 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 @@ -273,7 +264,7 @@ &GStreamer; already supports many basic media types. Following is a table of a few of the basic types used for buffers in - &GStreamer;. The table contains the name ("mime type") and a + &GStreamer;. The table contains the name ("media 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 . @@ -285,7 +276,7 @@ - Mime Type + Media Type Description Property Property Type diff --git a/docs/pwg/intro-preface.xml b/docs/pwg/intro-preface.xml index e6b868c170..bb6699fcf8 100644 --- a/docs/pwg/intro-preface.xml +++ b/docs/pwg/intro-preface.xml @@ -23,7 +23,7 @@ The pipeline design is made to have little overhead above what the applied filters induce. This makes &GStreamer; a good framework for designing even high-end audio applications which put high demands on - latency. + latency or performance. @@ -40,15 +40,13 @@ The framework is based on plugins that will provide the various codec and other functionality. The plugins can be linked and arranged in - a pipeline. This pipeline defines the flow of the data. Pipelines can - also be edited with a GUI editor and saved as XML so that pipeline - libraries can be made with a minimum of effort. + a pipeline. This pipeline defines the flow of the data. The &GStreamer; core function is to provide a framework for plugins, - data flow and media type handling/negotiation. It also provides an - API to write applications using the various plugins. + data flow, synchronization and media type handling/negotiation. It + also provides an API to write applications using the various plugins. @@ -289,7 +287,7 @@ - Adding new mime-types to the registry along with typedetect functions. + Adding new media types to the registry along with typedetect functions. This will allow your plugin to operate on a completely new media type.