From 19d24d40a141c1fbc0430b564f2343c996d5c00e Mon Sep 17 00:00:00 2001 From: Michael Roitzsch Date: Sun, 2 May 2004 19:52:12 +0000 Subject: start documenting the post plugin system (almost finished) CVS patchset: 6479 CVS date: 2004/05/02 19:52:12 --- doc/hackersguide/output.sgml | 359 ++++++++++++++++++++++++++++++++++++++++ doc/hackersguide/post_frame.fig | 347 ++++++++++++++++++++++++++++++++++++++ doc/hackersguide/stream.sgml | 6 +- 3 files changed, 711 insertions(+), 1 deletion(-) create mode 100644 doc/hackersguide/post_frame.fig (limited to 'doc') 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 @@ -1,6 +1,365 @@ xine's output layer + + Post plugin layer + + In this section you will learn, how the powerful post plugin architecture + works and how to write post plugins. + + + General principle of post plugins + + 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 + xine_post_wire() is used by frontends to form such + connections. + + + 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 xine.h + as XINE_POST_DATA_* defines. + + + Some terminology used in the following explanations: + + + + down direction: + 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. + + + + + up direction: + The direction from the output to the decoders. This is the way some video or audio + metadata like metronom timestamps travel through the engine. + + + + + interception: + 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. + + + + + + + Writing a xine post plugin + + The post plugin API is declared in src/xine-engine/post.h + The plugin info of post plugins contains the post plugin type, which is one of the + XINE_POST_TYPE_* defines and the init_class function of the plugin. + + +    post_plugin_t *open_plugin(post_class_t *class_gen, int inputs, xine_audio_port_t **audio_target, xine_video_port_t **video_target); + Returns an instance of the plugin. Some post plugins evaluate inputs + 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 post_plugin_t, which you are + encouraged to use: _x_post_init(). + + +    char *get_identifier(post_class_t *class_gen); + This function returns a short identifier describing the plugin. + + +    char *get_description(post_class_t *class_gen); + This function returns a plaintext, one-line string describing the plugin. + + +    void dispose(post_class_t *class_gen); + This function frees the memory used by the video out plugin class object. + + + The post_plugin_t 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 dispose() function and some internal stuff which + plugins do not have to worry about. + + +    void dispose(post_plugin_t *this_gen); + 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 dispose() is being called. + They maintain a usage counter to detect that. To check for such a condition, you + should use the _x_post_dispose() helper function like that: + +   if (_x_post_dispose(this)) +     really_free(this); + _x_post_dispose() frees any ressources allocated by any of the + post plugin helper functions and returns boolean true, if the plugin is not needed + any more. + + + + Interception + + 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. + + + Intercepting a video port + + +   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); + This function will intercept port 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, input or output 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. + + + post_video_port_t 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 new_port. You can use original_port + 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 + _x_post_inc_usage() before calling + original_port->open() and use the macro + _x_post_dec_usage() after calling + original_port->close(). Note that _x_post_dec_usage() + might dispose the plugin, when dispose() has been called + earlier and usage count drops to zero, so do never touch plugin structures after + _x_post_dec_usage(). In addition, you must never call a port + function of the original port when the port is not open. + + + Intercepting video frames or the overlay manager of the port is even easier. + You do not have to reimplement get_frame() or + get_overlay_manager(). Just enter a intercept_frame + or intercept_ovl function which returns boolean true, if + you want to intercept. The functions to insert in the intercepted frame or overlay + manager are taken from new_frame and new_manager + 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. + + + For convenience post_video_port_t 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 port_lock, frame_lock or + manager_lock respectively. + + + + Intercepting an audio port + + 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. + + + + Intercepting overlay manager + +    void _x_post_intercept_overlay_manager(video_overlay_manager_t *original, post_video_port_t *port); + Interception of the overlay manager is done automatically when your + intercept_ovl() 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 port->new_manager and stores the original + manager in port->original_manager. + + + No matter how you intercepted the overlay manager, your own replacement + functions will receive port->new_manager as the overlay manager + argument. But you most likely want to have access to the post_video_port_t + from within your functions. For that, there exists a pointer retrieval function: +    post_video_port_t *_x_post_ovl_manager_to_port(video_overlay_manager_t *manager); + + + + Intercepting a video frame + + +   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); + Interception of video frames is done automatically when your + intercept_frame() decision function returns boolean true or + when there is no such function in post_video_port_t. + Should you ever decide not to use that, interception can be done with the helper + function _x_post_intercept_video_frame(). + + + 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, _x_post_intercept_video_frame() + provides a shallow copy of the frame structure with the original frame attached to + copy->next. This copy will be filled with your own + frame functions from port->new_frame 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 frame->next. + _x_post_restore_video_frame() reverses this and should be + used when the frame is freed or disposed. + + + Your own replacement functions will receive the copied frame as as argument. + But you most likely want to have access to the post_video_port_t + from within your functions. For that, there exists a pointer retrieval function: +    post_video_port_t *_x_post_video_frame_to_port(vo_frame_t *frame); + 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 + _x_post_inc_usage() before calling + _x_post_intercept_video_frame() and use the macro + _x_post_dec_usage() after calling + _x_post_restore_video_frame(). Note that _x_post_dec_usage() + might dispose the plugin, when dispose() has been called + earlier and usage count drops to zero, so do never touch plugin structures after + _x_post_dec_usage(). + + + From within your own frame functions, you can propagate calls to the original + frame by calling a function on frame->next. 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 _x_post_frame_copy_down() + and _x_post_frame_copy_up() helper functions like that: + +   _x_post_frame_copy_down(frame, frame->next); +   frame->next->draw(frame->next, stream); +   _x_post_frame_copy_up(frame, frame->next); + + + 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: + +   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); + + + When the output receives a frame via draw(), + 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 + frame->next->draw() 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 _x_post_frame_u_turn() + when the frame is drawn, because this does some housekeeping which the + decoder might expect to take place. + + + The following diagram summarizes the situations of a video frame passing + through a post plugin: + + + + + + + + + + video frame passing through a post plugin + + + + + Summary of constraints + + + + Call _x_post_inc_usage() before port open() + before any other port function. + + + + + Call _x_post_inc_usage() before issueing an intercepted frame. + + + + + Call _x_post_dec_usage() after port close() + and do not call any port functions after that. + + + + + Call _x_post_dec_usage() after restoring a frame. + + + + + 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. + + + + + If your post plugin keeps locked frames, release them when your input port is being + closed. + + + + + Do not assume your plugin is alive after _x_post_dec_usage(). + + + + + + + + Video output 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 open() and + close() functions of xine_video_port_t + and xine_audio_port_t.) A buffer has a decoder_flags field which can have -- cgit v1.2.3