diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/hackersguide/output.sgml | 359 | ||||
| -rw-r--r-- | doc/hackersguide/post_frame.fig | 347 | ||||
| -rw-r--r-- | doc/hackersguide/stream.sgml | 6 |
3 files changed, 711 insertions, 1 deletions
diff --git a/doc/hackersguide/output.sgml b/doc/hackersguide/output.sgml index 97a54ce77..523d188bc 100644 --- a/doc/hackersguide/output.sgml +++ b/doc/hackersguide/output.sgml @@ -2,6 +2,365 @@ <title>xine's output layer</title> <sect1> + <title>Post plugin layer</title> + <para> + In this section you will learn, how the powerful post plugin architecture + works and how to write post plugins. + </para> + <sect2> + <title>General principle of post plugins</title> + <para> + The name "post plugin" comes from "postprocessing" which already describes + what these plugins are supposed to do: they take video frames, audio + buffers or subpicture planes as they leave the decoders and apply arbitrary + processing to them. Then they pass processed elements on to the output + loops. Post plugins can not only be chained to process the predecessor's + output and advance the data to their successor, they can form arbitrary trees, + since post plugins can have any number of inputs and outputs. Additionally, + the interconnection of the plugins currently inserted in such a tree can + be changed on the fly during playback. The public function + <function>xine_post_wire()</function> is used by frontends to form such + connections. + </para> + <para> + Due to the variety of possible applications, the interface post plugins have + to implement is just the basic foundation. The complexity comes from hooking + your post plugin into the engine data paths for video frames and audio buffers, + intercepting the data and performing your operation on them. This is done by + taking the interface of a video or audio port, replacing some of the functions + with your own ones and passing the interface to the decoder or predecessor + post plugin that is going to feed you with data by accessing this interface + and by doing that, calling the functions you provide. From there you can do + almost anything you want. Constructing video frames from audio buffers to + visualize sound is possible as well as just outputting an integer giving the + average brightness of an image. It is also possible to invent post plugins + with no output (not very useful, unless the plugin has some side-effect) or + no input at all; for the latter you have to create your own pthread, otherwise + your plugin will not do anything. An audio signal generator could be + implemented like this. The various data types, post plugins can + accept as input or offer as output are defined in <filename>xine.h</filename> + as <varname>XINE_POST_DATA_*</varname> defines. + </para> + <para> + Some terminology used in the following explanations: + <itemizedlist> + <listitem> + <para> + <varname>down direction</varname>: + The direction from the decoders to the output. This is the way video or audio + data (actual content and meta information) usually travels through the engine. + </para> + </listitem> + <listitem> + <para> + <varname>up direction</varname>: + The direction from the output to the decoders. This is the way some video or audio + metadata like metronom timestamps travel through the engine. + </para> + </listitem> + <listitem> + <para> + <varname>interception</varname>: + Post plugins are inserted into the engine data paths by the means of the decorator + design pattern. This works by taking engine structures with member funtions like + video or audio ports, video frames or overlay managers and inserting your own functions + into a copy of this structure. This is called interception. This modified structure + is then passed up to the plugin that uses it and thus calls your replaced functions. + </para> + </listitem> + </itemizedlist> + </para> + </sect2> + <sect2> + <title>Writing a xine post plugin</title> + <para> + The post plugin API is declared in <filename>src/xine-engine/post.h</filename> + The plugin info of post plugins contains the post plugin type, which is one of the + <varname>XINE_POST_TYPE_*</varname> defines and the init_class function of the plugin. + </para> + <para> + <programlisting> post_plugin_t *open_plugin(post_class_t *class_gen, int inputs, xine_audio_port_t **audio_target, xine_video_port_t **video_target);</programlisting> + Returns an instance of the plugin. Some post plugins evaluate <varname>inputs</varname> + to open a variable number of inputs. Since almost all post plugins have audio or video + outputs, you can hand in a NULL-terminated array of ports to connect to these outputs. + In this function you can also intercept these ports so that your plugin is actually used. + There is a helper function to initialize a <type>post_plugin_t</type>, which you are + encouraged to use: <function>_x_post_init()</function>. + </para> + <para> + <programlisting> char *get_identifier(post_class_t *class_gen);</programlisting> + This function returns a short identifier describing the plugin. + </para> + <para> + <programlisting> char *get_description(post_class_t *class_gen);</programlisting> + This function returns a plaintext, one-line string describing the plugin. + </para> + <para> + <programlisting> void dispose(post_class_t *class_gen);</programlisting> + This function frees the memory used by the video out plugin class object. + </para> + <para> + The <type>post_plugin_t</type> structure contains the publicly visible + part of the post plugin with the audio and video inputs and the type of + the post plugin. Not publicly visible are the lists of all inputs and outputs, + the <function>dispose()</function> function and some internal stuff which + plugins do not have to worry about. + </para> + <para> + <programlisting> void dispose(post_plugin_t *this_gen);</programlisting> + This function frees the memory used by the plugin instance, but not necessarily + immediately. Since post plugins enter their own functions into engine structures, + they might still be needed when <function>dispose()</function> is being called. + They maintain a usage counter to detect that. To check for such a condition, you + should use the <function>_x_post_dispose()</function> helper function like that: + <programlisting> + if (_x_post_dispose(this)) + really_free(this);</programlisting> + <function>_x_post_dispose()</function> frees any ressources allocated by any of the + post plugin helper functions and returns boolean true, if the plugin is not needed + any more. + </para> + </sect2> + <sect2> + <title>Interception</title> + <para> + Currently, we have four engine structures which can be intercepted by post plugins: + video ports, video frames, overlay managers and audio ports. You could do this + interception manually, but since this is quite a complex process, there are helper + functions to assist you and their usage is encouraged. + </para> + <sect3> + <title>Intercepting a video port</title> + <para> + <programlisting> + post_video_port_t *_x_post_intercept_video_port(post_plugin_t *post, + xine_video_port_t *port, post_in_t **input, post_out_t **output);</programlisting> + This function will intercept <varname>port</varname> and returns a structure + for you to pass up. All functions in the port will be replaced with dummy + pass through functions that do nothing but relaying the call down to the original + port. If you want (that is, <varname>input</varname> or <varname>output</varname> are + not NULL), this function will also create the input and output descriptors complete + with rewiring functions and add them to the relevant lists. + This is required, if you want this port to be advertised by the plugin to the outside world. + </para> + <para> + <type>post_video_port_t</type> makes a variety of interception schemes very easy. + If you want to replace any of the default functions with your own, just enter it + into <varname>new_port</varname>. You can use <varname>original_port</varname> + from within your function to propagate calls down to the original port. + The constraint is that your functions have to ensure that every original + port held open scores one usage counter point, so that opened ports are always + closed before the plugin is disposed. Therefore, you should use the macro + <function>_x_post_inc_usage()</function> before calling + <function>original_port->open()</function> and use the macro + <function>_x_post_dec_usage()</function> after calling + <function>original_port->close()</function>. Note that <function>_x_post_dec_usage()</function> + might dispose the plugin, when <function>dispose()</function> has been called + earlier and usage count drops to zero, so do never touch plugin structures after + <function>_x_post_dec_usage()</function>. In addition, you must never call a port + function of the original port when the port is not open. + </para> + <para> + Intercepting video frames or the overlay manager of the port is even easier. + You do not have to reimplement <function>get_frame()</function> or + <function>get_overlay_manager()</function>. Just enter a <varname>intercept_frame</varname> + or <varname>intercept_ovl</varname> function which returns boolean true, if + you want to intercept. The functions to insert in the intercepted frame or overlay + manager are taken from <varname>new_frame</varname> and <varname>new_manager</varname> + respectively. Note that the defaults are reversed: If you do not enter such a + decision function for either one, all frames and no overlay manager will be intercepted. + </para> + <para> + For convenience <type>post_video_port_t</type> also contains pointers to the + current stream and to the current post plugin and a user_data pointer, where you + can put in anything you need in addition. If your port is used by more than one + thread, you can also enforce locking on the port, frame or overlay manager level + by entering a lock into <varname>port_lock</varname>, <varname>frame_lock</varname> or + <varname>manager_lock</varname> respectively. + </para> + </sect3> + <sect3> + <title>Intercepting an audio port</title> + <para> + Audio port interception is just a stripped down version of video port interception. + Everything related to frames and overlay manager is not needed and audio buffers + do not need to be intercepted, since they have no member functions. Everything else + of the above still applies. + </para> + </sect3> + <sect3> + <title>Intercepting overlay manager</title> + <para> + <programlisting> void _x_post_intercept_overlay_manager(video_overlay_manager_t *original, post_video_port_t *port);</programlisting> + Interception of the overlay manager is done automatically when your + <function>intercept_ovl()</function> decision function returns boolean true. + Should you ever decide not to use that, interception can be done with this helper + function, which simply creates an intercepted overlay manager with dummy + pass through functions in <varname>port->new_manager</varname> and stores the original + manager in <varname>port->original_manager</varname>. + </para> + <para> + No matter how you intercepted the overlay manager, your own replacement + functions will receive <varname>port->new_manager</varname> as the overlay manager + argument. But you most likely want to have access to the <type>post_video_port_t</type> + from within your functions. For that, there exists a pointer retrieval function: + <programlisting> post_video_port_t *_x_post_ovl_manager_to_port(video_overlay_manager_t *manager);</programlisting> + </para> + </sect3> + <sect3> + <title>Intercepting a video frame</title> + <para> + <programlisting> + vo_frame_t *_x_post_intercept_video_frame(vo_frame_t *frame, post_video_port_t *port); + vo_frame_t *_x_post_restore_video_frame(vo_frame_t *frame, post_video_port_t *port);</programlisting> + Interception of video frames is done automatically when your + <function>intercept_frame()</function> decision function returns boolean true or + when there is no such function in <type>post_video_port_t</type>. + Should you ever decide not to use that, interception can be done with the helper + function <function>_x_post_intercept_video_frame()</function>. + </para> + <para> + Since the same video frame can be in use in the decoder and in the output and in + any post plugin in between at the same time, simply modifying the frame + structure does not work, because every user of the frame needs to see his version + and the frame must always travel along the same path through the plugins for its + entire lifetime. To ensure that, <function>_x_post_intercept_video_frame()</function> + provides a shallow copy of the frame structure with the original frame attached to + <varname>copy->next</varname>. This copy will be filled with your own + frame functions from <varname>port->new_frame</varname> and with dummy pass + through functions for those you did not provide. This way, every part of xine + using this frame will see its own frame structure with a list of frame + contexts from down the data path attached to <varname>frame->next</varname>. + <function>_x_post_restore_video_frame()</function> reverses this and should be + used when the frame is freed or disposed. + </para> + <para> + Your own replacement functions will receive the copied frame as as argument. + But you most likely want to have access to the <type>post_video_port_t</type> + from within your functions. For that, there exists a pointer retrieval function: + <programlisting> post_video_port_t *_x_post_video_frame_to_port(vo_frame_t *frame);</programlisting> + The constraint is that your functions have to ensure that every intercepted + frame scores one usage counter point, so that these frames are always + freed or disposed before the plugin is disposed. Therefore, you should use the macro + <function>_x_post_inc_usage()</function> before calling + <function>_x_post_intercept_video_frame()</function> and use the macro + <function>_x_post_dec_usage()</function> after calling + <function>_x_post_restore_video_frame()</function>. Note that <function>_x_post_dec_usage()</function> + might dispose the plugin, when <function>dispose()</function> has been called + earlier and usage count drops to zero, so do never touch plugin structures after + <function>_x_post_dec_usage()</function>. + </para> + <para> + From within your own frame functions, you can propagate calls to the original + frame by calling a function on <varname>frame->next</varname>. Since + modifications to the frame can travel both upwards and downwards (decoders and + output can modify the frame), changes need to be copied between the frame + structure contexts. You should use the <function>_x_post_frame_copy_down()</function> + and <function>_x_post_frame_copy_up()</function> helper functions like that: + <programlisting> + _x_post_frame_copy_down(frame, frame->next); + frame->next->draw(frame->next, stream); + _x_post_frame_copy_up(frame, frame->next);</programlisting> + </para> + <para> + If your post plugin modifies the content of the frame, you have to modify + a deep copy of the frame, because the decoder might still use the frame as + a reference frame for future decoding. The usual procedure is: + <programlisting> + modified_frame = port->original_port->get_frame(port->original_port, ...); + _x_post_frame_copy_down(frame, modified_frame); + copy_and_modify(frame, modified_frame); + skip = modified_frame->draw(modified_frame, stream); + _x_post_frame_copy_up(frame, modified_frame); + modified_frame->free(modified_frame);</programlisting> + </para> + <para> + When the output receives a frame via <function>draw()</function>, + it usually receives the stream where the frame + originates as well and modifies the state of this stream by passing + the frame through the stream's metronom. Sometimes this is unwanted. + For example, when you pass the same frame to the output more than once, it + will confuse metronom. To solve this, you can call + <function>frame->next->draw()</function> with NULL as the stream. + You might also want to prevent frames from being passed down to the output + completely, because your post plugin creates something else from these frames, + but does not need them to be drawn. In both these situations, you have + to call the helper function <function>_x_post_frame_u_turn()</function> + when the frame is drawn, because this does some housekeeping which the + decoder might expect to take place. + </para> + <para> + The following diagram summarizes the situations of a video frame passing + through a post plugin: + </para> + <mediaobject> + <imageobject> + <imagedata fileref="post_frame.png" format="PNG"> + </imageobject> + <imageobject> + <imagedata fileref="post_frame.eps" format="EPS"> + </imageobject> + <caption> + <para>video frame passing through a post plugin</para> + </caption> + </mediaobject> + </sect3> + <sect3> + <title>Summary of constraints</title> + <itemizedlist> + <listitem> + <para> + Call <function>_x_post_inc_usage()</function> before port <function>open()</function> + before any other port function. + </para> + </listitem> + <listitem> + <para> + Call <function>_x_post_inc_usage()</function> before issueing an intercepted frame. + </para> + </listitem> + <listitem> + <para> + Call <function>_x_post_dec_usage()</function> after port <function>close()</function> + and do not call any port functions after that. + </para> + </listitem> + <listitem> + <para> + Call <function>_x_post_dec_usage()</function> after restoring a frame. + </para> + </listitem> + <listitem> + <para> + When a frame is drawn through your plugin, it must either be drawn on the original + port with the correct stream as argument or U-turned. + </para> + </listitem> + <listitem> + <para> + If your post plugin keeps locked frames, release them when your input port is being + closed. + </para> + </listitem> + <listitem> + <para> + Do not assume your plugin is alive after <function>_x_post_dec_usage()</function>. + </para> + </listitem> + </itemizedlist> + </sect3> + </sect2> +<!-- + <sect2> + <title>Rewiring and the ticket system</title> + <para> + TODO + </para> + </sect2> +--> + </sect1> + + <sect1> <title>Video output</title> <para> In order to allow for device-dependant acceleration features, xine diff --git a/doc/hackersguide/post_frame.fig b/doc/hackersguide/post_frame.fig new file mode 100644 index 000000000..4f576abdd --- /dev/null +++ b/doc/hackersguide/post_frame.fig @@ -0,0 +1,347 @@ +#FIG 3.2 +Landscape +Center +Metric +A4 +100.00 +Single +-2 +1200 2 +6 2970 585 9360 9945 +2 1 0 2 0 7 50 0 -1 0.000 0 0 -1 0 0 3 + 3015 900 3915 900 3915 630 +2 2 0 2 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 3015 630 9315 630 9315 9900 3015 9900 3015 630 +4 0 0 50 0 20 11 0.0000 4 165 675 3105 810 post plugin\001 +-6 +6 5040 1125 7200 1530 +2 2 0 1 0 4 40 0 20 0.000 0 0 -1 0 0 5 + 5040 1125 7200 1125 7200 1530 5040 1530 5040 1125 +4 0 0 30 0 20 11 0.0000 4 165 1545 5220 1395 _x_post_intercept_frame\001 +-6 +6 3645 990 4635 1620 +2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 + 3735 1080 4635 1080 4635 1620 3735 1620 3735 1080 +2 2 0 1 0 4 30 0 20 0.000 0 0 -1 0 0 5 + 3645 990 4545 990 4545 1530 3645 1530 3645 990 +-6 +6 5040 2160 7200 2565 +2 2 0 1 0 7 40 0 20 0.000 0 0 -1 0 0 5 + 5040 2160 7200 2160 7200 2565 5040 2565 5040 2160 +4 0 0 30 0 20 11 0.0000 4 165 1710 5220 2430 _x_post_frame_copy_down\001 +-6 +6 5040 3060 7200 3465 +2 2 0 1 0 7 40 0 20 0.000 0 0 -1 0 0 5 + 5040 3060 7200 3060 7200 3465 5040 3465 5040 3060 +4 0 0 30 0 20 11 0.0000 4 165 1530 5220 3330 _x_post_frame_copy_up\001 +-6 +6 3645 2025 4635 2655 +2 2 0 1 0 4 30 0 20 0.000 0 0 -1 0 0 5 + 3645 2025 4545 2025 4545 2565 3645 2565 3645 2025 +2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 + 3735 2115 4635 2115 4635 2655 3735 2655 3735 2115 +4 0 0 20 0 18 25 0.0000 4 270 225 3825 2430 d\001 +-6 +6 7830 2025 8820 2655 +2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 + 7920 2115 8820 2115 8820 2655 7920 2655 7920 2115 +2 2 0 1 0 4 30 0 -1 0.000 0 0 -1 0 0 5 + 7830 2025 8730 2025 8730 2565 7830 2565 7830 2025 +4 0 0 20 0 18 25 0.0000 4 270 225 8100 2520 d\001 +-6 +6 7830 2925 8820 3555 +2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 + 7920 3015 8820 3015 8820 3555 7920 3555 7920 3015 +2 2 0 1 0 4 30 0 -1 0.000 0 0 -1 0 0 5 + 7830 2925 8730 2925 8730 3465 7830 3465 7830 2925 +4 0 0 20 0 18 25 0.0000 4 285 555 8100 3420 d u\001 +-6 +6 3645 2925 4635 3555 +2 2 0 1 0 4 30 0 20 0.000 0 0 -1 0 0 5 + 3645 2925 4545 2925 4545 3465 3645 3465 3645 2925 +2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 + 3735 3015 4635 3015 4635 3555 3735 3555 3735 3015 +4 0 0 20 0 18 25 0.0000 4 285 555 3825 3330 d u\001 +-6 +6 7875 4725 8775 5265 +2 2 0 1 0 3 40 0 15 0.000 0 0 -1 0 0 5 + 7875 4725 8775 4725 8775 5265 7875 5265 7875 4725 +4 0 0 20 0 18 25 0.0000 4 270 225 8055 5130 d\001 +-6 +6 3645 4005 4635 4635 +2 2 0 1 0 4 30 0 20 0.000 0 0 -1 0 0 5 + 3645 4005 4545 4005 4545 4545 3645 4545 3645 4005 +2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 + 3735 4095 4635 4095 4635 4635 3735 4635 3735 4095 +4 0 0 20 0 18 25 0.0000 4 270 225 3825 4410 d\001 +-6 +6 7875 6300 8775 6840 +2 2 0 1 0 3 40 0 15 0.000 0 0 -1 0 0 5 + 7875 6300 8775 6300 8775 6840 7875 6840 7875 6300 +4 0 0 20 0 18 25 0.0000 4 285 555 8055 6705 d u\001 +-6 +6 7875 5625 8775 6165 +2 2 0 1 0 3 40 0 15 0.000 0 0 -1 0 0 5 + 7875 5625 8775 5625 8775 6165 7875 6165 7875 5625 +4 0 0 20 0 18 25 0.0000 4 285 555 8055 6030 d u\001 +-6 +6 3645 7245 4635 7875 +2 2 0 1 0 4 30 0 20 0.000 0 0 -1 0 0 5 + 3645 7245 4545 7245 4545 7785 3645 7785 3645 7245 +2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 + 3735 7335 4635 7335 4635 7875 3735 7875 3735 7335 +4 0 0 20 0 18 25 0.0000 4 270 225 3825 7650 d\001 +-6 +6 3645 8145 4635 8775 +2 2 0 1 0 4 30 0 20 0.000 0 0 -1 0 0 5 + 3645 8145 4545 8145 4545 8685 3645 8685 3645 8145 +2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 + 3735 8235 4635 8235 4635 8775 3735 8775 3735 8235 +4 0 0 20 0 18 25 0.0000 4 285 555 3825 8550 d u\001 +-6 +6 5040 7830 7200 8235 +2 2 0 1 0 7 40 0 20 0.000 0 0 -1 0 0 5 + 5040 7830 7200 7830 7200 8235 5040 8235 5040 7830 +4 0 0 30 0 20 11 0.0000 4 165 1395 5220 8100 _x_post_frame_u_turn\001 +-6 +6 990 1125 2340 1530 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 990 1125 2340 1125 2340 1530 990 1530 990 1125 +4 0 0 50 0 20 11 0.0000 4 165 630 1170 1395 get_frame\001 +-6 +6 990 2025 2340 3510 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 990 2025 2340 2025 2340 3510 990 3510 990 2025 +4 0 0 50 0 20 11 0.0000 4 120 255 1170 2475 field\001 +4 0 0 50 0 20 11 0.0000 4 120 255 1170 2700 lock\001 +4 0 0 50 0 20 11 0.0000 4 165 705 1170 2925 proc_frame\001 +4 0 0 50 0 20 11 0.0000 4 165 630 1170 3150 proc_slice\001 +4 0 0 50 0 20 11 0.0000 4 165 1065 1170 3375 proc_macroblock\001 +4 0 0 50 0 20 11 0.0000 4 120 300 1170 2250 draw\001 +-6 +6 990 4095 2340 6795 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 990 4095 2340 4095 2340 6795 990 6795 990 4095 +4 0 0 50 0 20 11 0.0000 4 120 255 1170 4555 field\001 +4 0 0 50 0 20 11 0.0000 4 120 255 1170 4761 lock\001 +4 0 0 50 0 20 11 0.0000 4 165 705 1170 4969 proc_frame\001 +4 0 0 50 0 20 11 0.0000 4 165 630 1170 5175 proc_slice\001 +4 0 0 50 0 20 11 0.0000 4 165 1065 1170 5383 proc_macroblock\001 +4 0 0 50 0 20 11 0.0000 4 120 300 1170 4347 draw\001 +-6 +6 990 7335 2340 8640 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 990 7335 2340 7335 2340 8640 990 8640 990 7335 +4 0 0 50 0 20 11 0.0000 4 120 300 1170 7605 draw\001 +-6 +6 9990 1125 11340 1530 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 9990 1125 11340 1125 11340 1530 9990 1530 9990 1125 +4 0 0 50 0 20 11 0.0000 4 165 630 10170 1395 get_frame\001 +-6 +6 9990 2025 11340 3510 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 9990 2025 11340 2025 11340 3510 9990 3510 9990 2025 +4 0 0 50 0 20 11 0.0000 4 120 255 10170 2475 field\001 +4 0 0 50 0 20 11 0.0000 4 120 255 10170 2700 lock\001 +4 0 0 50 0 20 11 0.0000 4 165 705 10170 2925 proc_frame\001 +4 0 0 50 0 20 11 0.0000 4 165 630 10170 3150 proc_slice\001 +4 0 0 50 0 20 11 0.0000 4 165 1065 10170 3375 proc_macroblock\001 +4 0 0 50 0 20 11 0.0000 4 120 300 10170 2250 draw\001 +-6 +6 9990 4140 11340 4545 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 9990 4140 11340 4140 11340 4545 9990 4545 9990 4140 +4 0 0 50 0 20 11 0.0000 4 165 630 10170 4410 get_frame\001 +-6 +6 9990 4725 11340 6210 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 9990 4725 11340 4725 11340 6210 9990 6210 9990 4725 +4 0 0 50 0 20 11 0.0000 4 120 255 10170 5175 field\001 +4 0 0 50 0 20 11 0.0000 4 120 255 10170 5400 lock\001 +4 0 0 50 0 20 11 0.0000 4 165 705 10170 5625 proc_frame\001 +4 0 0 50 0 20 11 0.0000 4 165 630 10170 5850 proc_slice\001 +4 0 0 50 0 20 11 0.0000 4 165 1065 10170 6075 proc_macroblock\001 +4 0 0 50 0 20 11 0.0000 4 120 300 10170 4950 draw\001 +-6 +6 9990 6390 11340 6795 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 9990 6390 11340 6390 11340 6795 9990 6795 9990 6390 +4 0 0 50 0 20 11 0.0000 4 120 240 10170 6660 free\001 +-6 +6 180 585 765 1755 +2 2 0 2 0 7 20 0 -1 6.000 0 0 -1 0 0 5 + 225 630 720 630 720 1710 225 1710 225 630 +4 0 0 20 0 20 15 1.5708 4 210 960 540 1665 interception\001 +-6 +6 180 1890 765 3735 +2 2 0 2 0 7 20 0 -1 6.000 0 0 -1 0 0 5 + 225 1935 720 1935 720 3690 225 3690 225 1935 +4 0 0 20 0 20 15 1.5708 4 225 1065 540 3375 pass through\001 +-6 +6 180 3870 765 7020 +2 2 0 2 0 7 20 0 -1 6.000 0 0 -1 0 0 5 + 225 3915 720 3915 720 6975 225 6975 225 3915 +4 0 0 20 0 20 15 1.5708 4 225 1380 540 6165 modifying a copy\001 +-6 +6 180 7155 765 8910 +2 2 0 2 0 7 20 0 -1 6.000 0 0 -1 0 0 5 + 225 7200 720 7200 720 8865 225 8865 225 7200 +4 0 0 20 0 20 15 1.5708 4 180 1245 540 8685 dead-end draw\001 +-6 +6 180 9045 765 9945 +2 2 0 2 0 7 20 0 -1 6.000 0 0 -1 0 0 5 + 225 9090 720 9090 720 9900 225 9900 225 9090 +4 0 0 20 0 20 15 1.5708 4 225 570 540 9810 freeing\001 +-6 +6 5040 4455 7200 4860 +2 2 0 1 0 7 40 0 20 0.000 0 0 -1 0 0 5 + 5040 4455 7200 4455 7200 4860 5040 4860 5040 4455 +4 0 0 30 0 20 11 0.0000 4 165 1710 5220 4725 _x_post_frame_copy_down\001 +-6 +6 5040 6030 7200 6435 +2 2 0 1 0 7 40 0 20 0.000 0 0 -1 0 0 5 + 5040 6030 7200 6030 7200 6435 5040 6435 5040 6030 +4 0 0 30 0 20 11 0.0000 4 165 1530 5220 6300 _x_post_frame_copy_up\001 +-6 +6 3645 6255 4635 6885 +2 2 0 1 0 4 30 0 20 0.000 0 0 -1 0 0 5 + 3645 6255 4545 6255 4545 6795 3645 6795 3645 6255 +2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 + 3735 6345 4635 6345 4635 6885 3735 6885 3735 6345 +4 0 0 20 0 18 25 0.0000 4 285 555 3825 6660 d u\001 +-6 +6 5040 9270 7200 9675 +2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 + 5040 9270 7200 9270 7200 9675 5040 9675 5040 9270 +4 0 0 30 0 20 11 0.0000 4 165 1845 5220 9540 _x_post_restore_video_frame\001 +-6 +6 990 9270 2340 9675 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 990 9270 2340 9270 2340 9675 990 9675 990 9270 +4 0 0 50 0 20 11 0.0000 4 165 855 1170 9540 free / dispose\001 +-6 +6 9990 9270 11340 9675 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 9990 9270 11340 9270 11340 9675 9990 9675 9990 9270 +4 0 0 50 0 20 11 0.0000 4 165 855 10170 9540 free / dispose\001 +-6 +6 6660 4995 7515 5580 +2 3 0 1 0 7 50 0 15 0.000 0 0 -1 0 0 4 + 7065 4995 6840 5220 7290 5220 7065 4995 +4 0 0 50 0 20 11 0.0000 4 150 825 6660 5400 modify frame\001 +4 0 0 50 0 20 11 0.0000 4 120 465 6840 5580 content\001 +-6 +6 405 10170 2970 11250 +6 990 10170 1980 10800 +2 2 0 1 0 7 40 0 20 0.000 0 0 -1 0 0 5 + 1080 10260 1980 10260 1980 10800 1080 10800 1080 10260 +2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 + 990 10170 1890 10170 1890 10710 990 10710 990 10170 +-6 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 + 1 1 1.00 120.00 180.00 + 630 11025 630 10440 990 10440 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 + 1 1 1.00 120.00 180.00 + 2340 11025 2340 10530 1980 10530 +4 0 0 20 0 20 15 0.0000 4 165 465 405 11250 frame\001 +4 0 0 20 0 20 15 0.0000 4 165 975 1980 11250 frame->next\001 +-6 +6 3375 10080 6300 11250 +2 2 0 1 0 4 40 0 20 0.000 0 0 -1 0 0 5 + 3375 10710 4275 10710 4275 11250 3375 11250 3375 10710 +2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 + 3375 10080 4275 10080 4275 10620 3375 10620 3375 10080 +4 0 0 50 0 20 15 0.0000 4 225 1890 4410 10440 frame from original port\001 +4 0 0 50 0 20 15 0.0000 4 210 1425 4410 11070 intercepted frame\001 +-6 +6 6660 10035 11250 11295 +6 8505 10035 9405 10575 +2 2 0 1 0 3 40 0 -1 0.000 0 0 -1 0 0 5 + 8505 10035 9405 10035 9405 10575 8505 10575 8505 10035 +4 0 0 20 0 18 25 0.0000 4 285 555 8685 10440 d u\001 +-6 +6 6660 10170 8055 11295 +4 2 0 50 0 20 15 0.0000 4 165 1005 8055 10350 downstream\001 +4 2 0 50 0 20 15 0.0000 4 165 1380 8055 10650 meta-information\001 +4 2 0 50 0 20 15 0.0000 4 180 1080 8055 10950 from decoder\001 +4 2 0 50 0 20 15 0.0000 4 210 705 8055 11250 to output\001 +-6 +6 9855 10170 11250 11295 +4 0 0 50 0 20 15 0.0000 4 210 765 9855 10350 upstream\001 +4 0 0 50 0 20 15 0.0000 4 165 1380 9855 10650 meta-information\001 +4 0 0 50 0 20 15 0.0000 4 210 915 9855 10950 from output\001 +4 0 0 50 0 20 15 0.0000 4 180 870 9855 11250 to decoder\001 +-6 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 + 1 1 1.00 120.00 180.00 + 8100 10800 8775 10800 8775 10485 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 + 1 1 1.00 120.00 180.00 + 9810 10800 9135 10800 9135 10485 +-6 +6 3645 9135 4635 9765 +2 2 0 1 0 4 30 0 20 0.000 0 0 -1 0 0 5 + 3645 9135 4545 9135 4545 9675 3645 9675 3645 9135 +2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 + 3735 9225 4635 9225 4635 9765 3735 9765 3735 9225 +4 0 0 20 0 18 25 0.0000 4 270 225 3825 9540 d\001 +-6 +6 7875 9180 8775 9720 +2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 + 7875 9180 8775 9180 8775 9720 7875 9720 7875 9180 +4 0 0 20 0 18 25 0.0000 4 270 225 8055 9585 d\001 +-6 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 1 0 2 + 0 0 1.00 120.00 180.00 + 9990 1305 7200 1305 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 1 0 2 + 0 0 1.00 120.00 180.00 + 5040 1305 2340 1305 +2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 + 7875 1035 8775 1035 8775 1575 7875 1575 7875 1035 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 1 0 2 + 0 0 1.00 120.00 180.00 + 2340 2340 9990 2340 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 1 0 2 + 0 0 1.00 120.00 180.00 + 9990 3240 2340 3240 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 1 0 4 + 0 0 1.00 120.00 180.00 + 2340 4320 5625 4320 5625 6570 2340 6570 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 1 0 4 + 0 0 1.00 120.00 180.00 + 9990 5895 6570 5895 6570 6570 9990 6570 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 1 0 4 + 0 0 1.00 120.00 180.00 + 9990 4320 6570 4320 6570 4995 9990 4995 +2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 + 7875 4050 8775 4050 8775 4590 7875 4590 7875 4050 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 1 0 4 + 0 0 1.00 120.00 180.00 + 2340 7560 5625 7560 5625 8460 2340 8460 +2 1 1 1 0 7 50 0 -1 10.000 0 0 -1 0 0 2 + 0 1800 11610 1800 +2 1 1 1 0 7 50 0 -1 10.000 0 0 -1 0 0 2 + 0 3780 11610 3780 +2 1 1 1 0 7 50 0 -1 10.000 0 0 -1 0 0 2 + 0 7065 11610 7065 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 1 0 2 + 0 0 1.00 120.00 180.00 + 2340 9450 5040 9450 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 1 0 2 + 0 0 1.00 120.00 180.00 + 7200 9450 9990 9450 +2 3 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 6 + 6075 90 6075 540 3195 540 3015 315 3195 90 6075 90 +2 3 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 6 + 6165 90 6165 540 9135 540 9315 315 9135 90 6165 90 +2 1 1 1 0 7 50 0 -1 10.000 0 0 -1 0 0 2 + 0 8955 11610 8955 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2 + 3195 9990 3195 11385 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2 + 6480 9990 6480 11385 +4 0 0 20 0 20 20 0.0000 4 210 270 5715 405 up\001 +4 0 0 20 0 20 20 0.0000 4 210 585 6300 405 down\001 diff --git a/doc/hackersguide/stream.sgml b/doc/hackersguide/stream.sgml index c5460f029..3b92e3058 100644 --- a/doc/hackersguide/stream.sgml +++ b/doc/hackersguide/stream.sgml @@ -542,7 +542,11 @@ This function performs the bulk of the decoding work. The xine engine delivers buffers (xine_buffer_t data types) to this function and it is up to this function to assemble the parts of the buffer, decode the data, and - send the decoded data to the proper output unit. + send the decoded data to the proper output unit. The constraint is that + you must never call a port function of the output port when the port has + not been opened by you. (See the <function>open()</function> and + <function>close()</function> functions of <type>xine_video_port_t</type> + and <type>xine_audio_port_t</type>.) </para> <para> A buffer has a <varname>decoder_flags</varname> field which can have |