1The purpose of this README is to document the various bits of the page code
2in the PLplot core that interacts with devices (such as ps, xwin) where
3pages are included in the standard and devices that have no paging (such as
4png, svg, pngcairo, svgcairo) where PLplot logical pages must be handled as
5separate (familied) files.
6
7plsc->page_status keeps track of page status which is one of AT_BOP,
8DRAWING, or AT_EOP.
9
10plP_line, plP_polyline, plP_fill, and plP_image set
11
12plsc->page_status = DRAWING
13
14plP_tidy sets no page_status, but that is only called from plend1 (see below)
15so it transcends page_status.
16
17QUESTION TO BE ANSWERED LATER: should page_status be set to DRAWING for
18plP_state, and plP_esc?
19
20Page and family related code fragments:
21
22* plinit ==> plP_init initializes page_status
23 plsc->page_status = AT_EOP;
24
25* plinit ==> plP_bop
26
27* plP_bop
28
29 plP_subpInit();
30
31* plP_subpInit initializes number of subpages (if not done already using
32 plssub, plstar, or plstart) and current subpage.
33
34 if (plsc->nsubx <= 0)
35 plsc->nsubx = 1;
36 if (plsc->nsuby <= 0)
37 plsc->nsuby = 1;
38
39 plsc->cursub = 0;
40
41* plP_bop (continued) does nothing after above plP_subpInit call
42 if already at beginning of page (as set by plP_init above)
43
44 if (plsc->page_status == AT_BOP)
45 return;
46
47 plsc->page_status = AT_BOP;
48
49* plP_eop is a no-op if already at eop.
50
51 if (plsc->page_status == AT_EOP)
52 return;
53
54 plsc->page_status = AT_EOP;
55
56* plbop
57 plP_bop();
58 plsc->cursub = 1;
59
60* pleop
61
62 plsc->cursub = plsc->nsubx * plsc->nsuby;
63 plP_eop();
64
65
66* pladv(0) calls plP_eop and plP_bop IF the subpages on the current page
67 have been completed as indicated by plsc->cursub. Note, because of
68 the above initialization by plP_subpInit, this does NOT occur if you
69 call pladv(0) right after plinit.
70
71 if (plsc->cursub >= plsc->nsubx * plsc->nsuby) {
72 plP_eop();
73 plP_bop();
74 plsc->cursub = 1;
75 }
76
77* plend calls plend1 for each stream.
78
79* plend1
80 if (plsc->level > 0) {
81 plP_eop();
82 plP_tidy();
83 plsc->level = 0;
84 }
85
86
87* plGetFam calls plP_tidy and plP_init to start next familied file. It also
88restores the initial page status (in all cases so far this internal function
89is called by device drivers from their plD_bop-* function so this initial
90page status is necessarily AT_BOP in the use so far) that otherwise is
91changed to AT_EOP by the plP_init call. This restoration is necessary to
92have valid empty pages for some devices (e.g., svg).
93
94In sum, plP_bop is called from plinit, plbop, and pladv. The dispatch table
95part of it is never done if already at bop. plP_eop is called from pleop,
96pladv, and plend1 and is a noop if already at eop. plP_tidy is called from
97both plGetFam (used internally by drivers to handle familying) and plend1.
98
99The usual patterns of using the public api functions plbop and pleop on the
100one hand, or pladv(0) or plenv (which calls pladv(0))
101on the other is as follows:
102
103Single page:
104
105plinit, plend (example 5)
106plinit, pladv(0), plend (example 10 where I don't think that pladv(0) is
107 actually required.)
108plinit, plenv, plend (the plenv here does lots of other essential stuff
109 beside the pladv(0) which is not really necessary)
110
111Multiple pages:
112
113plinit, plbop, pleop, plbop, pleop, ..., plend (example 2 which also uses
114pladv(0) for each page in context of advancing the subpage set up by plssub)
115
116plinit, pladv(0), pladv(0),..., plend (example 7)
117plinit, plenv, plenv,..., plend (example 22)
118
119Note, mixing the plbop/pleop method and the pladv(0) (or plenv) method of
120handling _pages_ is not recommended. Of course, pladv(0) can be used to
121advance _subpages_ within the plbop/pleop method (see example 2) and
122presumably also the pladv(0) (or plenv) method of handling pages.
123