diff options
| -rw-r--r-- | doc/Makefile.am | 4 | ||||
| -rw-r--r-- | doc/README | 34 | ||||
| -rw-r--r-- | doc/README.config_en | 19 | ||||
| -rw-r--r-- | doc/README.logging | 76 | ||||
| -rw-r--r-- | doc/README.mrl | 76 | ||||
| -rw-r--r-- | doc/README.plugins | 192 |
6 files changed, 29 insertions, 372 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index e626af771..f518eec5b 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -30,3 +30,7 @@ uninstall-local: rm -f $$dir/$$name; \ echo "removing $$dir/$$name" ; \ done + +docs: + @cd faq && $(MAKE) $@ + @cd hackersguide && $(MAKE) $@ diff --git a/doc/README b/doc/README index 62932b79a..b20d016b8 100644 --- a/doc/README +++ b/doc/README @@ -14,15 +14,31 @@ faq/ README.config_en details about xine engine config options +README.dvb + instructions on how to get DVB (DigitalTV) working in xine + +README.dxr3 +README.dxr3_pl + instructions on how to get use the DXR3 (hollywood+) in xine + README.freebsd hints on running xine on FreeBSD README.irix hints on running xine on IRIX +README.mrl + defines exactly what MRLs (media resource locators) are + +README.network_dvd + how to play DVDs / Audio CDs over the network + README.opengl how to use xine's OpenGL video output +README.plugins + information about plugin concepts in xine for developers + README.solaris hints on running xine on Solaris @@ -32,22 +48,6 @@ README.syncfb README.tvmode how to get tv output working -README.dvb - instructions on how to get DVB (DigitalTV) working in xine - -README.dxr3 -README.dxr3_pl - instructions on how to get use the DXR3 (hollywood+) in xine - -README.mrl - defines exactly what MRLs (media resource locators) are - -README.plugins - information about plugin concepts in xine for developers - -README.network_dvd - how to play DVDs / Audio CDs over the network - man/ contains some general manpages about xine-lib @@ -55,4 +55,4 @@ hackersguide/ contains the xine hacker's guide for developers dvb_channels - sample channel file for DVB
\ No newline at end of file + sample channel file for DVB diff --git a/doc/README.config_en b/doc/README.config_en index 3e3b891d9..a1afb82d9 100644 --- a/doc/README.config_en +++ b/doc/README.config_en @@ -39,9 +39,9 @@ audio.alsa_a52_device Device name used for a/52 passthrough. audio.alsa_mmap_enable Enable mmap mode. 0 = Old mode, 1 = mmap mode. Should use less cpu in mmap mode. -audio.driver audio driver to use, same as command line +audio.driver audio driver to use, same as xine-ui's command line option -A - (e.g. alsa05, alsa09, arts, esd, sun) + (e.g. alsa, oss, arts, esd, sun) audio.force_rate If non-zero, force audio output rate to specified value for systems with braindead audio drivers that @@ -73,7 +73,7 @@ audio.mixer_volume 0..100%: Mixer volume. audio.oss_sync_method Type of audio/video synchronization desired auto: System attempts to automatically - detect thhe optimal type of audio/ + detect the optimal type of audio/ video synchronization, with the preference order being GETODELAY, GETOPTR, and finally SOFTSYNC @@ -103,21 +103,20 @@ audio.oss_sync_method Type of audio/video synchronization desired support the real-time ioctl's and you experienced sync errors after long playbacks. - audio.oss_device_num -1, 0-16: Forces the OSS plugin to use the specified dspX device, regardless of its capabilities. If -1 (default) is specified, the audio device with the best capabilities will be used. Note: /dev/dsp is usually a symlink to /dev/dsp0 - + audio.oss_latency For softsync you can manually adjust the default a/v sync latency here. The units are in miliseconds, so if the sound seems delayed 1 second from the video set it to 1000. (default value = 0) audio.passthrough_offset the audio offset for passthrough output. - The unit is PTS (1/90000s), defaults to 10000. + The unit is PTS (1/90000s), defaults to 0. audio.sun_static_delay sun driver static delay (latency) @@ -137,8 +136,6 @@ codec.a52_surround_downmix Enable audio downmixing to 2.0 surround stereo. (0) off [default] (1) on -codec.divx4_XXX see README.divx4 - codec.ffmpeg_illegal_vlc 1/0: allow illegal vlc codes in mpeg4 streams. allow playing videos created with MS ISO MPEG4 codec. warning: error resilience will be disabled. @@ -179,8 +176,8 @@ input.file_hidden_files hidden files displaying (filenames starting with dot) -miscelaneus values: -------------------- +miscellaneous values: +--------------------- misc.demux_strategy 0..3: Demuxer detection strategy. (see xine.h for details about values). @@ -281,4 +278,4 @@ video.num_buffers Number of video buffers (8k each) xine --- version of this file: - $Id: README.config_en,v 1.3 2003/06/06 14:05:31 jcdutton Exp $ + $Id: README.config_en,v 1.4 2003/10/12 19:07:40 mroi Exp $ diff --git a/doc/README.logging b/doc/README.logging deleted file mode 100644 index 145207252..000000000 --- a/doc/README.logging +++ /dev/null @@ -1,76 +0,0 @@ -The xine logging system -======================= - -xine offers a wide range of possibilities to display -strings. This document should describe when to use -which way and how to do it right. - - -xine_log --------- -Output which is done thru this function will be -displayed by the frontend. It can not be disabled. -If xine->verbosity is not 0 the messages will also -be displayed on the console. Often these strings -are translated. -This function is for information which the user should -read always. - -usage: xine_log(xine_t *xine, int buf, const char *format, ...); - -buf is either XINE_LOG_MSG for general messages or - XINE_LOG_PLUGIN for messages about plugins. - - -xprintf -------- -This macro uses the xine->verbosity value to decide -if the string should be printed to the console. Possible -values are XINE_VERBOSITY_NONE, XINE_VERBOSITY_LOG or -XINE_VERBOSITY_DEBUG. By default nothing is printed. -When you use xine-ui you can enable this output with -the --verbose=[1,2] options. -This function should be used for information which the -user should only read up on request. - -usage: xprintf(xine_t *xine, int verbosity, const char *format, ...); - - -lprintf/llprintf ----------------- -These macros are for debugging purpose only. Under normal -circumstances it is disabled. And can only be enabled by changing -a define statement and a recompilation. It has to be enabled for these -files that are of interest. -It should only be use for information which is intended for developers. - -usage: lprintf(const char *format, ...); - llprintf(cat , const char *format, ...); - where cat is a flag which enables or disables this logging. - - --lprintf can be enabled by defining LOG at the top of the source file: -#define LOG - --llprintf can used for more than one categorie per file by using diffent lables: -#define LOG_LOAD 1 -#define LOG_SAVE 0 - -llprintf(LOG_LOAD, "loading was successful\n"); -llprintf(LOG_SAVE, "could not save to file %s\n", filename); - -in this case only hte first messages is printed. To enable/disable change the -defines. - --LOG_MODULE should be used to set the modulename for xprintf/lprintf/llprintf. -Each output line starts with "modulename: ": -#define LOG_MODULE "modulename" - --LOG_VERBOSE should be set to enable the logging of functionname and linenumbers: -#define LOG_VERBOSE - -then the output will be: -modulename: (function_name:42) message - - - - diff --git a/doc/README.mrl b/doc/README.mrl deleted file mode 100644 index f2d343e28..000000000 --- a/doc/README.mrl +++ /dev/null @@ -1,76 +0,0 @@ -proposition of generic syntax of MRLs -===================================== - -This document defines a draft for a syntactic specification of MRLs as -used by xine-lib. The language of MRLs is designed to be a true subset -of the language of URIs as given in RFC2396. A type 2 grammar for the -language of MRLs is given in EBNF below. - -Semantically, MRLs consist of two distinct parts that are evaluated by -different components of the xine architecture. The first part, -derivable from the symbol <input_source> in the given grammar, is -completely handed to the input plugins, with input plugins signaling -if they can handle the MRL. -The second part, derivable from <stream_setup> and delimited from the -first by a crosshatch ('#') contains parameters that modify the -initialization and playback behaviour of the stream to which the MRL -is passed. The possible parameters are mentioned in the manpage to -xine-ui. - -The following definition should be regarded as a guideline only. -Of course any given input plugin only understands a subset of all -possible MRLs. On the other hand, invalid MRLs according to this -definition might be understood for convenience reasons. -Some user awareness is required at this point. - -EBNF grammar for MRLs: - -<mrl> ::= <input_source>[#<stream_setup>] -<input_source> ::= (<absolute_mrl>|<relative_mrl>) -<absolute_mrl> ::= <input>:(<net_path>|<abs_path>)[?<query>] -<relative_mrl> ::= (<abs_path>|<rel_path>) -<net_path> ::= //<authority>[<abs_path>] -<abs_path> ::= /<path_segments> -<rel_path> ::= <rel_segment>[<abs_path>] -<rel_segment> ::= <rel_char>{<rel_char>} -<rel_char> ::= (<unreserved>|<escaped>|;|@|&|=|+|$|,) -<input> ::= <alpha>{(<alpha>|<digit>|+|-|.)} -<authority> ::= (<server>|<reg_name>) -<server> ::= [[<userinfo>@]<host>[:<port>]] -<userinfo> ::= {(<unreserved>|<escaped>|;|:|&|=|+|$|,)} -<host> ::= (<hostname>|<ipv4_address>) -<hostname> ::= {<domainlabel>.}<toplabel>[.] -<domainlabel> ::= (<alphanum>|<alphanum>{(<alphanum>|-)}<alphanum>) -<toplabel> ::= (<alpha>|<alpha>{(<alphanum>|-)}<alphanum>) -<ipv4_address> ::= <digit>{<digit>}.<digit>{<digit>}.<digit>{<digit>}.<digit>{<digit>} -<port> ::= {<digit>} -<reg_name> ::= <reg_char>{<reg_char>} -<reg_char> ::= (<unreserved>|<escaped>|;|:|@|&|=|+|$|,) -<path_segments> ::= <segment>{/<segment>} -<segment> ::= {<path_char>}{;<param>} -<param> ::= {<path_char>} -<path_char> ::= (<unreserved>|<escaped>|:|@|&|=|+|$|,) -<query> ::= {<mrl_char>} -<stream_setup> ::= <stream_option>;{<stream_option>} -<stream_option> ::= (<configoption>|<engine_option>|novideo|noaudio|nospu) -<configoption> ::= <configentry>:<configvalue> -<configentry> ::= <unreserved>{<unreserved>} -<configvalue> ::= <conf_char>{<conf_char>} -<engine_option> ::= <unreserved>{<unreserved>}:<stream_char>{<stream_char>} -<stream_char> ::= (<unreserved>|<escaped>|:|@|&|=|+|$|,) -<mrl_char> ::= (<reserved>|<unreserved>|<escaped>) -<reserved> ::= (;|/|?|:|@|&|=|+|$|,) -<unreserved> ::= (<alphanum>|<mark>) -<mark> ::= (-|_|.|!|~|*|'|(|)) -<escaped> ::= %<hex><hex> -<hex> ::= (<digit>|A|B|C|D|E|F|a|b|c|d|e|f) -<alphanum> ::= (<alpha>|<digit>) -<alpha> ::= (<lowalpha>|<upalpha>) -<lowalpha> ::= (a|b|c|d|e|f|g|h|i|j|k|l|m|n|o|p|q|r|s|t|u|v|w|x|y|z) -<upalpha> ::= (A|B|C|D|E|F|G|H|I|J|K|L|M|N|O|P|Q|R|S|T|U|V|W|X|Y|Z) -<digit> ::= (0|1|2|3|4|5|6|7|8|9) - - ---- -version of this file: - $Id: README.mrl,v 1.1 2003/01/05 13:11:53 guenter Exp $ diff --git a/doc/README.plugins b/doc/README.plugins deleted file mode 100644 index 72109e0fd..000000000 --- a/doc/README.plugins +++ /dev/null @@ -1,192 +0,0 @@ -The (new) xine plugin system -============================ - -The plugin system enables some of xine's most valuable features: - -- drop-in extensiability - (we have always had this...) -- support parallel installation of multiple (incompatible) libxine versions -- support for multiple plugin directories - (/usr/lib/xine/plugins + $HOME/.xine/plugins + /usr/local/... + ...) -- support for recursive plugin directories - (plugins are found even in subdirectories of the plugin directories) -- version management - On start, xine finds all plugins in its plugin (sub)directories and - chooses an appropriate version (usually the newest) for each plugin -- simplification - plugins don't have to follow any special naming convention any more, - and any plugin may contain an arbitrary subset of input, demuxer, - decoder or output plugins. - -User view ---------- - - -Developer view - How it works ------------------------------ - -Essentally, plugins are just shared objects, ie dynamic libraries. In -contrast to normal dynamic libraries, they are stored outside of the -system's library PATHs and libxine does its own bookkeeping, which -enables most advanced features mentioned above. - -The plugin mechanism is mainly defined by 3 components, namely plugin -location (file system layout), plugin content (what's inside the .so?) -and the loading mechanism. Each of those has a dedicated section here: - -Plugin location and filesystem layout -------------------------------------- - -The primary goal for this new plugin mechanism was the need to support -simultaneous installation of several (most likely incompatible) -libxine versions without them overwriting each other's -plugins. Therefore, we have this simple layout: - -Plugins are installed below XINE_PLUGINDIR (/usr/local/lib/xine/plugins -by default). -Note that plugins are _never_ directly installed into XINE_PLUGINDIR. -Instead, a separate subdirectory is created for any "plugin -provider". A plugin provider is equivalent with the exact version of -one source package. Typical examples include "xine-lib-0.9.11" or -"xine-dvdnav-1.0". Every source package is free to install an -arbitrary number of plugins in its own, private directory. If a -package installs several plugins, they may optionally be organized -further into subdirectories. - -So you will finally end up with something like this: - -/usr/local/ lib/xine/plugins - xine-lib-0.9.11 - demux_mpeg_block.so - decode_mpeg.so - video_out_xv.so - ... - xine-dvdnav-0.9.11 - input_dvdnav.so - xine-lib-1.2 - input - file.so - stdin_fifo.so - vcd.so - demuxers - fli.so - avi.so - ... - decoders - ffmpeg.so - mpeg.so (may contain mpeg 1/2 audio and video decoders) - pcm.so - ... - output - video_xv.so - audio_oss.so - ... - xine-lib-3.0 - avi.so (avi demuxer) - mpeg.so (contains mpeg demuxers and audio/video decoders) - video_out_xv.so (Xv video out) - ... - -As you can see, every package is free to organize plugins at will -below its own plugin provider directory. - -Additionally, administrators may choose to put plugins directly into -XINE_PLUGINDIR, or in a "local" subdirectory. -Users may wish to put additional plugins in ~/.xine/plugins/. -Again, there may be subdirectories to help organize the plugins. - - -Plugin Content: What's inside the .so? --------------------------------------- - -Each plugin library (.so file) contains an arbitrary number of (virtual) -plugins. Typically, it will contain exactly one plugin. However, it -may be useful to put a set of related plugins in one library, so they -can share common code. - -First of all, what is a virtual plugin? -A virtual plugin is essentially a structure that is defined by the -xine engine. This structure typically contains lots of function -pointers to the actual API functions. -For each plugin API, there are several API versions, and each API -version may specify a new, incompatible structure. Therefore, it is -essential that only those plugins are loaded that support current -libxine's API, so the .so file needs a "plugin directory" that -provides libxine with the version information, even before it tries to -load any of the plugins. - -This plugin directory is helt in an array named "xine_plugin_info", -which is defined like this: - -plugin.h: ---------- -#define PLUGIN_NONE 0 -#define PLUGIN_INPUT 1 -#define PLUGIN_DEMUX 2 -#define PLUGIN_AUDIO_CODEC 3 -... - -struct plugin_info_s { - uint8_t plugin_type; /* one of the PLUGIN_* constants above */ - uint8_t plugin_API; /* API version supported by this plugin */ - const char *plugin_id; /* a name that identifies this plugin */ - uint32_t plugin_version; /* version number, increased every release */ - plugin_t *(*init)(void); /* used to get/initialize an instance */ -}; -typedef struct plugin_info_s plugin_info_t; - -a fictitious file input plugin that supports input plugin API 12 and -13, found in xine-lib 2.13.7 would then define this plugin directory: - -input_file.c: ------------- -#include <xine/plugin.h> -... -plugin_t *(*init_api12)(void) { - input_plugin_t *this; - - this = malloc(sizeof(input_plugin_t)); - ... - return (plugin_t *) this; -} -/* same thing, with different initialization for API 13 */ - -const plugin_info_t xine_plugin_info[] = { - { PLUGIN_INPUT, 12, "file", 21307, init_api12 }, - { PLUGIN_INPUT, 13, "file", 21307, init_api13 }, - { PLUGIN_NONE, 0, "", 0, NULL } -} - -Notes: ------ -This input plugin supports two APIs, other plugins might provide a -mixture of demuxer and decoder plugins that belong together somehow -(ie. share common code). - -The init function itself doesn't have to check API versions any more. - -The xine_plugin_info list must be terminated by a dummy entry for a -"PLUGIN_NONE" plugin. - -The plugin version number is generated from xine-lib's version number -like this: MAJOR * 10000 + MINOR * 100 + SUBMINOR. (2.13.7 => 21307) -This is not required, but it's an easy way to ensure that the version -increases for every release. - -The structure of xine_plugin_info may _never_ be changed. If it ever -needs to be changed, it must be renamed to avoid erraneous loading of -incompatible plugin directories. - - -Plugin Loader Mechanism ------------------------ - -The plugin loader needs two passes over the plugins: - -1) all configured plugin directories are recursively scanned, - collecting all compatible versions of all the available plugins - -2) for each virtual plugin (identified by plugin_id), the newest - version found above is selected and loaded. - - |