1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/layout/doc/frame_reflow_debug.html Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,224 @@
1.4 +<!-- This Source Code Form is subject to the terms of the Mozilla Public
1.5 + - License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
1.7 +
1.8 +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
1.9 +<html>
1.10 + <head>
1.11 + <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
1.12 + <style type="text/css">
1.13 + body {font-family:arial}
1.14 +.log {background-color:silver; color:blue}
1.15 + </style>
1.16 + <title> Debugging Frame Reflow</title>
1.17 + </head>
1.18 + <body>
1.19 +<h1>Debugging Frame Reflow HowTo</h1>
1.20 +<h2>General Overview</h2>
1.21 +<p> The frame reflow can be logged with the debug capabilities implemented in <a href="http://lxr.mozilla.org/seamonkey/source/layout/html/base/src/nsFrame.cpp"><code>nsFrame.cpp</code></a>.
1.22 +It provides the following information for each frame at the
1.23 +start of its reflow
1.24 +<ul>
1.25 +<li>reflow reason
1.26 +<li>available width, available height
1.27 +<li>computed width, computed height
1.28 +<li>the previous and the next frame in flow
1.29 +<li>and a count number.
1.30 +</ul>
1.31 +<p>When the frame's reflow is finished the following information is displayed :</p>
1.32 +<ul>
1.33 +<li>reflow metric (desired) width, height
1.34 +<li>max. element size (MES) width
1.35 +<li>maximum Width
1.36 +<li>frame status
1.37 +<li>overflow area
1.38 +</ul>
1.39 +
1.40 +<h2>Getting the log</h2>
1.41 +<ul>
1.42 +<li>Make sure that your build is a <b>debug</b> build.
1.43 +<li>Create a text file (for instance <code>reflow_rules.txt</code>).
1.44 +<li>Enter this line in the text file <pre>* 1</pre>
1.45 +<li>Save the text file in the <code>%DIST%</code> directory
1.46 +<li>Go to the <code>%DIST%</code> directory
1.47 +<li>enter from command line: <code>set GECKO_DISPLAY_REFLOW_RULES_FILE=reflow_rules.txt</code>
1.48 +<li> Run <code>viewer > logfile.txt</code> and load your testcase. The
1.49 +logfile will contain all the promised information.
1.50 +</ul>
1.51 +<h2>Log File analyis</h2>
1.52 +<p>The logfile for a simple table like</p>
1.53 +<pre>
1.54 +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
1.55 +<html>
1.56 +<head>
1.57 + <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
1.58 +</head>
1.59 +<body>
1.60 +<table width="100">
1.61 + <tbody>
1.62 + <tr>
1.63 + <td>foo</td>
1.64 + </tr>
1.65 + </tbody>
1.66 +</table>
1.67 +</body>
1.68 +</html>
1.69 +</pre>
1.70 +
1.71 +<p> will create the following log:</p>
1.72 +<table class="log"><tr><td>
1.73 +<pre>
1.74 +VP 00B97C30 r=0 a=9180,4470 c=9180,4470 cnt=856
1.75 + scroll 00B97EE0 r=0 a=9180,4470 c=9180,4470 cnt=857
1.76 + scroll 00B97EE0 r=0 a=9180,4470 c=9180,4470 cnt=858
1.77 + canvas 00B97C6C r=0 a=9180,UC c=9180,4470 cnt=859
1.78 + area 02D7AFE4 r=0 a=9180,UC c=9180,UC cnt=860
1.79 + text 02D7B150 r=0 a=9180,UC c=UC,UC cnt=861
1.80 + text 02D7B150 d=0,0
1.81 + block 02D7B210 r=0 a=9180,UC c=8940,UC cnt=862
1.82 + block 02D7B210 d=8940,0
1.83 + area 02D7AFE4 d=9180,120
1.84 + canvas 00B97C6C d=9180,4470
1.85 + scroll 00B97EE0 d=9180,4470
1.86 + scroll 00B97EE0 d=9180,4470
1.87 +VP 00B97C30 d=9180,4470
1.88 +VP 00B97C30 r=1 a=9180,4470 c=9180,4470 cnt=863
1.89 + scroll 00B97EE0 r=1 a=9180,4470 c=9180,4470 cnt=864
1.90 + scroll 00B97EE0 r=1 a=9180,4470 c=9180,4470 cnt=865
1.91 + canvas 00B97C6C r=1 a=9180,UC c=9180,4470 cnt=866
1.92 + area 02D7AFE4 r=1 a=9180,UC c=9180,UC cnt=867
1.93 + block 02D7B210 r=1 a=9180,UC c=8940,UC cnt=868
1.94 + text 02D7B3F8 r=0 a=8940,UC c=UC,UC cnt=869
1.95 + text 02D7B3F8 d=0,0
1.96 + tblO 02D7B5F0 r=0 a=8940,UC c=0,0 cnt=870
1.97 + tbl 02D7B7EC r=0 a=8940,UC c=1500,UC cnt=871
1.98 + rowG 00B984A4 r=0 a=UC,UC c=UC,UC cnt=872
1.99 + row 02D7BAF8 r=0 a=UC,UC c=UC,UC cnt=873
1.100 + cell 02D7BC98 r=0 a=UC,UC c=UC,UC cnt=874
1.101 + block 02D7BCF8 r=0 a=UC,UC c=UC,UC cnt=875
1.102 + text 02D7BE84 r=0 a=UC,UC c=UC,UC cnt=876
1.103 + text 02D7BE84 d=300,285 me=300
1.104 + block 02D7BCF8 d=300,300 me=300
1.105 + cell 02D7BC98 d=330,330 me=330
1.106 + row 02D7BAF8 d=UC,330
1.107 + rowG 00B984A4 d=UC,330
1.108 + colG 02D7BFB0 r=0 a=UC,UC c=UC,UC cnt=877
1.109 + col 02D7C0D8 r=0 a=0,0 c=1500,UC cnt=878
1.110 + col 02D7C0D8 d=0,0
1.111 + colG 02D7BFB0 d=0,0
1.112 + rowG 00B984A4 r=2 a=1500,UC c=1500,UC cnt=879
1.113 + row 02D7BAF8 r=2 a=1500,UC c=1500,UC cnt=880
1.114 + cell 02D7BC98 r=2 a=1440,UC c=1410,UC cnt=881
1.115 + block 02D7BCF8 r=2 a=1410,UC c=1410,UC cnt=882
1.116 + block 02D7BCF8 d=1410,300
1.117 + cell 02D7BC98 d=1440,330
1.118 + row 02D7BAF8 d=1500,330
1.119 + rowG 00B984A4 d=1500,330
1.120 + colG 02D7BFB0 r=2 a=1500,UC c=1500,UC cnt=883
1.121 + col 02D7C0D8 r=0 a=0,0 c=1500,UC cnt=884
1.122 + col 02D7C0D8 d=0,0
1.123 + colG 02D7BFB0 d=0,0
1.124 + tbl 02D7B7EC d=1500,390
1.125 + tblO 02D7B5F0 d=1500,390
1.126 + text 02D7C130 r=0 a=8940,UC c=UC,UC cnt=885
1.127 + text 02D7C130 d=0,0
1.128 + block 02D7B210 d=8940,390
1.129 + area 02D7AFE4 d=9180,630
1.130 + canvas 00B97C6C d=9180,4470
1.131 + scroll 00B97EE0 d=9180,4470
1.132 + scroll 00B97EE0 d=9180,4470
1.133 +VP 00B97C30 d=9180,4470
1.134 +</pre>
1.135 +</td></tr></table>
1.136 +<p>
1.137 +The first line shows the reflow of the viewport (<code class="log">VP</code>). This viewport has the address <code class="log">00B97C30</code>. It is the initial reflow: <code class="log">r=0</code>. Other reflow reasons are: </p>
1.138 +<table>
1.139 +<tr><td>1</td><td>incremental reflow</td></tr>
1.140 +<tr><td>2</td><td>resize reflow</td></tr>
1.141 +<tr><td>3</td><td>style change reflow</td></tr>
1.142 +<tr><td>4</td><td>dirty reflow.</td></tr>
1.143 +</table>
1.144 +
1.145 +<p>The available width is 9180 twips. The available height is 4470 twips (<code class="log">a=9180,4470</code>). The computed width is 9180 twips. The computed height is 4470 twips (<code class="log">c=9180,4470</code>). The line count is 856 (<code class="log">cnt=856</code>).
1.146 +<p>
1.147 +Below this is a line that reads:<p><code class="log">tblO 02D7B5F0 r=0 a=8940,UC c=0,0 cnt=870</code></p><p> Here the <code class="log">UC</code> shows that on initial reflow the available height for the outer table frame is unconstrained.
1.148 +<p>
1.149 +The table cell requires its children to compute the MES. It is reported back from the block as:
1.150 +<p><code class="log">block 02D7BCF8 d=300,300 me=300</code></p>
1.151 +<p>The block max. element size is 300 twips.
1.152 +<p> The second table reflow is started at
1.153 +<p><code class="log">rowG 00B984A4 r=2 a=1500,UC c=1500,UC cnt=879</code></p>
1.154 +<p>where the previous information is used.
1.155 +The block has been required to compute the max. element size only once and it reports now:
1.156 +<p> <code class="log">block 02D7BCF8 d=1410,300</code></p>
1.157 +<p>The block shows the same address as the previous one.
1.158 +<p>Frames with children that overflow the parent will return <code>PR_TRUE</code> from <code>HasOverflowRect()</code>. For these frames
1.159 +the overflow area is displayed as <code class="log">block 025ED8F0 d=8940,1020 o=(0,0) 9180 x 1020</code>. The overflow area is specified as (x,y) origin and width x height.
1.160 +<p> The reflow finishes at the same level where it started.
1.161 +
1.162 +<h2>Advanced reflow debugging</h2>
1.163 +<p>The previously described technique dumps the data for every frame. Sometimes the log is clearer if only the main frames are shown.
1.164 +The entries in the reflow log can be controlled on a frame level. For instance adding <code>text 0</code> to the rules in <code>reflow_rules.txt</code> would hide the text entries from the reflow. The display of the following frames can be turned on by adding a line with the frame name and <code>1</code> or turned off by adding a line with the frame name and <code>0</code>:</p>
1.165 +<table cellspacing="5">
1.166 + <tr><th style="text-align:left">short name</th><th style="text-align:left">layout tag</th></tr>
1.167 + <tr><td>area</td><td>area</td></tr>
1.168 + <tr><td>block</td><td>block</td></tr>
1.169 + <tr><td>br</td><td>br</td></tr>
1.170 + <tr><td>bullet</td><td>bullet</td></tr>
1.171 + <tr><td>button</td><td>gfxButtonControl</td></tr>
1.172 + <tr><td>hr</td><td>hr</td></tr>
1.173 + <tr><td>frameI</td><td>htmlFrameInner</td></tr>
1.174 + <tr><td>frameO</td><td>htmlFrameOuter</td></tr>
1.175 + <tr><td>img</td><td>image</td></tr>
1.176 + <tr><td>inline</td><td>inline</td></tr>
1.177 + <tr><td>letter</td><td>letter</td></tr>
1.178 + <tr><td>line</td><td>line</td></tr>
1.179 + <tr><td>select</td><td>select</td></tr>
1.180 + <tr><td>obj</td><td>object</td></tr>
1.181 + <tr><td>page</td><td>page</td></tr>
1.182 + <tr><td>place</td><td>placeholder</td></tr>
1.183 + <tr><td>canvas</td><td>canvas</td></tr>
1.184 + <tr><td>root</td><td>root</td></tr>
1.185 + <tr><td>scroll</td><td>scroll</td></tr>
1.186 + <tr><td>caption</td><td>tableCaption</td></tr>
1.187 + <tr><td>cell</td><td>tableCell</td></tr>
1.188 + <tr><td>bcCell</td><td>bcTableCell</td></tr>
1.189 + <tr><td>col</td><td>tableCol</td></tr>
1.190 + <tr><td>colG</td><td>tableColGroup</td></tr>
1.191 + <tr><td> tbl</td><td>table</td></tr>
1.192 + <tr><td>tblO</td><td>tableOuter</td></tr>
1.193 + <tr><td>rowG</td><td>tableRowGroup</td></tr>
1.194 + <tr><td>row</td><td>tableRow</td></tr>
1.195 + <tr><td>textCtl</td><td>textInput</td></tr>
1.196 + <tr><td>text</td><td>text</td></tr>
1.197 + <tr><td>VP</td><td>viewport</td></tr>
1.198 +</table>
1.199 +<p>Once the problem is reduced to a single frame level, placing a breakpoint at <code>DisplayReflowEnterPrint</code> in <a href="http://lxr.mozilla.org/seamonkey/source/layout/html/base/src/nsFrame.cpp"><code>nsFrame.cpp</code></a> is a very efficient way to step through
1.200 + the reflow tree.
1.201 +
1.202 +<h2>Other reflow debug options</h2>
1.203 +
1.204 +<h3>GECKO_DISPLAY_REFLOW_FLAG_PIXEL_ERRORS</h3>
1.205 +<p>
1.206 +Setting this option via <code>set GECKO_DISPLAY_REFLOW_FLAG_PIXEL_ERRORS = 1</code> enables a verification for each coordinate value that the coordinates are aligned at pixel boundaries.
1.207 +<table class="log"><tr><td>
1.208 +<pre>
1.209 + row 0268A594 r=0 a=UC,UC c=UC,20 cnt=870
1.210 +VALUE 20 is not a whole pixel
1.211 + cell 0268A6C0 r=0 a=UC,UC c=UC,15 cnt=871
1.212 + block 0268A764 r=0 a=UC,UC c=UC,UC cnt=872
1.213 + block 0268A764 d=0,0 me=0
1.214 + cell 0268A6C0 d=0,0 me=0
1.215 + row 0268A594 d=UC,20
1.216 +VALUE 20 is not a whole pixel
1.217 + rowG 0268A02C d=UC,695
1.218 +VALUE 695 is not a whole pixel</pre>
1.219 +</td></tr></table>
1.220 +<p>
1.221 +While unaligned values at the entrance of a frame reflow can be ignored, when they appear at the exit of a routine this can cause display errors like stray lines. OS2 is very vulnerable to pixel alignement errors as text is drawn on pixel boundaries.
1.222 +
1.223 +<h3>GECKO_DISPLAY_REFLOW_INDENT_UNDISPLAYED_FRAMES</h3>
1.224 +<p>
1.225 +Setting this option via <code>set GECKO_DISPLAY_REFLOW_INDENT_UNDISPLAYED_FRAMES = 1</code> will cause an advance of the indent even for frames which are blocked via the reflow rules file.
1.226 + </body>
1.227 +</html>
