[doc] misc. patchs & small improvements
[scilab.git] / scilab / modules / gui / help / en_US / usecanvas.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="usecanvas">
3     <refnamediv>
4         <refname>usecanvas</refname>
5         <refpurpose>Get/Set the main component used for Scilab graphics.</refpurpose>
6     </refnamediv>
7     <refsynopsisdiv>
8         <title>Syntax</title>
9         <synopsis>
10             [canvasused] = usecanvas([usecanvasfordisplay]);
11         </synopsis>
12     </refsynopsisdiv>
13     <refsection>
14         <title>Arguments</title>
15         <variablelist>
16             <varlistentry>
17                 <term>canvasused</term>
18                 <listitem>
19                     <para>Boolean:</para>
20                     <itemizedlist>
21                         <listitem>
22                             <para>
23                                 <literal>%T</literal> if a "GLCanvas" is used for graphics display (Mixing uicontrols and graphics <emphasis role="bold">not available</emphasis>).
24                             </para>
25                         </listitem>
26                         <listitem>
27                             <para>
28                                 <literal>%F</literal> if a "GLJPanel" is used for graphics display (Mixing uicontrols and graphics available).
29                             </para>
30                         </listitem>
31                     </itemizedlist>
32                 </listitem>
33             </varlistentry>
34             <varlistentry>
35                 <term>usecanvasfordisplay</term>
36                 <listitem>
37                     <para>Boolean:</para>
38                     <itemizedlist>
39                         <listitem>
40                             <para>
41                                 <literal>%T</literal> to use a "GLCanvas" for graphics display (Mixing uicontrols and graphics <emphasis role="bold">not available</emphasis>).
42                             </para>
43                         </listitem>
44                         <listitem>
45                             <para>
46                                 <literal>%F</literal> to use a "GLJPanel" for graphics display (Mixing uicontrols and graphics available).
47                             </para>
48                         </listitem>
49                     </itemizedlist>
50                 </listitem>
51             </varlistentry>
52         </variablelist>
53     </refsection>
54     <refsection>
55         <title>Description</title>
56         <para>Scilab uses a "GLJPanel" (a Swing OpenGL component) to display graphics (plot3d, plot, ...). This component uses some high level OpenGL primitives which are not correctly supported on some platforms (depending on the operating system, video cards, drivers ...)</para>
57         <para>
58             "GLCanvas" (AWT + OpenGL) is an alternative component provided by the Java Framework. Scilab can use it to render graphics. <emphasis role="bold">However, using this component disables some capabilities such as mixing plots and uicontrols (see demo GUI/UIcontrol2). That is why it is not the default behavior.</emphasis>
59         </para>
60         <para>In some particular cases, the use of the "GLCanvas" component is forced when Scilab starts (a warning message is displayed when a graphics function is used for the first time), here is a list of these cases:</para>
61         <informaltable border="2">
62             <tr>
63                 <td align="center">
64                     <emphasis role="bold">Operating System</emphasis>
65                 </td>
66                 <td align="center">
67                     <emphasis role="bold">Video Card</emphasis>
68                 </td>
69                 <td align="center">
70                     <emphasis role="bold">Details</emphasis>
71                 </td>
72             </tr>
73             <tr>
74                 <td align="center">64-bits Windows</td>
75                 <td align="center">All</td>
76                 <td align="center">When Scilab is used in a remote session.</td>
77             </tr>
78             <tr>
79                 <td rowspan="3" valign="middle" align="center">Linux</td>
80                 <td align="center">NVIDIA Card</td>
81                 <td align="center">With free drivers.</td>
82             </tr>
83             <tr>
84                 <td align="center">ATI Card</td>
85                 <td align="center">With free drivers or ATI-drivers with version &lt; 8.52.3 (Installer version &lt; 8.8 / OpenGL version &lt; 2.1.7873).</td>
86             </tr>
87             <tr>
88                 <td align="center">INTEL Card</td>
89                 <td align="center">With Direct Rendering activated.</td>
90             </tr>
91         </informaltable>
92         <para>
93             You can also dynamically activate this component through Scilab using <literal>usecanvas</literal>:
94         </para>
95         <itemizedlist>
96             <listitem>
97                 <para>
98                     <literal>usecanvas(%T)</literal> will use "GLCanvas" for plot rendering.
99                 </para>
100             </listitem>
101             <listitem>
102                 <para>
103                     <literal>usecanvas(%F)</literal> will use "GLJPanel" for plot rendering. If your configuration is known as a one having problems with "GLJPanel" (See table above), a warning message will be displayed.
104                 </para>
105             </listitem>
106         </itemizedlist>
107         <para>
108             If you believe your configuration is able to use the "GLJPanel" and Scilab automatically forces the use of "GLCanvas", you can test your configuration by switching to "GLJPanel" (<literal>usecanvas(%F)</literal>) and try to plot something (<literal>plot3d()</literal> for example). If Scilab graphics work, please inform us about it by sending an email to <literal>scilab.support@scilab.org</literal> and giving us your Operating System/Video Card/Video Card driver version: this will help us to improve future versions of Scilab.
109         </para>
110     </refsection>
111     <refsection>
112         <title>Workaround</title>
113         <para>This code fixes most of the potential issues related to graphic cards issues. Please note that decreases the performances.
114             <programlisting role="example"><![CDATA[
115     system_setproperty("jogl.gljpanel.nohw","");
116     ]]></programlisting>
117         </para>
118     </refsection>
119     <!-- This part comes from http://wiki.scilab.org/Graphical_issues_with_Scilab_5.0 -->
120     <refsection>
121         <title>Technical Aspects</title>
122         <para>
123             Since version 5.0, Scilab is doing an advanced use of JOGL (the Java Binding for the OpenGL), which is using the Java2D OpenGL Pipeline. For performance reasons, we use the Java2D OpenGL Pipeline. From a more technical aspect, it uses the internal buffer of the graphic cards called <literal>pbuffer</literal>.
124         </para>
125         <para>Problems may occur when the driver of the graphic card does not support properly this approach. As far as we know, there is no free driver under Linux handling this feature. In the proprietary world, the situation is as follows: </para>
126         <itemizedlist>
127             <listitem>
128                 <para>
129                     <literal>NVIDIA</literal>: Nvidia provides the appropriate proprietary drivers. Scilab's graphics work without any problem with most NVIDIA drivers.
130                 </para>
131             </listitem>
132             <listitem>
133                 <para>
134                     <literal>ATI</literal>: From the driver version 8.8, most ATI graphics supports the pbuffer under Linux.
135                 </para>
136             </listitem>
137             <listitem>
138                 <para>
139                     <literal>Intel</literal>: This is the big drawback of using the pbuffer. There is currently no support of pbuffer by any official Intel drivers under Linux.
140                 </para>
141             </listitem>
142         </itemizedlist>
143         <para>
144             There is a workaround for Linux to tackle this issue, but a solution is to use a software accelerated driver. To do it, in <literal>/etc/X11/xorg.conf</literal>, look for the <emphasis role="italic">Section "Device"</emphasis> and change the option <emphasis role="italic">Driver</emphasis> to <emphasis role="italic">vesa</emphasis>:
145         </para>
146         <programlisting role="example"><![CDATA[
147 Section "Device"
148         Identifier      "Your Graphic card"
149         Driver  "vesa"
150 [...]
151 EndSection
152  ]]></programlisting>
153         <para>Unfortunately, this solution makes Scilab pretty slow. </para>
154         <para>
155             Under Windows, video cards manufacturers update regularly and <literal>pbuffers</literal> are managed. Please download recent drivers at:
156         </para>
157         <itemizedlist>
158             <listitem>
159                 <para>
160                     For <literal>ATI cards</literal>: <ulink url="http://ati.amd.com/support/driver.html">http://ati.amd.com/support/driver.html</ulink>
161                 </para>
162             </listitem>
163             <listitem>
164                 <para>
165                     For <literal>Intel cards</literal>: <ulink url="http://www.intel.com/support/graphics/">http://www.intel.com/support/graphics/</ulink>
166                 </para>
167             </listitem>
168             <listitem>
169                 <para>
170                     For <literal>Matrox cards</literal>: <ulink url="http://www.matrox.com/graphics/en/support/drivers/">http://www.matrox.com/graphics/en/support/drivers/</ulink>
171                 </para>
172             </listitem>
173             <listitem>
174                 <para>
175                     For <literal>NVIDIA cards</literal>: <ulink url="http://www.nvidia.com/content/drivers/drivers.asp">http://www.nvidia.com/content/drivers/drivers.asp</ulink>
176                 </para>
177             </listitem>
178             <listitem>
179                 <para>
180                     For <literal>S3 cards</literal>: <ulink url="http://www.s3graphics.com/en/resources/drivers/index.jsp">http://www.s3graphics.com/en/resources/drivers/index.jsp</ulink>
181                 </para>
182             </listitem>
183             <listitem>
184                 <para>
185                     For <literal>SiS cards</literal>: <ulink url="http://www.sis.com/download/">http://www.sis.com/download/</ulink>
186                 </para>
187             </listitem>
188             <listitem>
189                 <para>
190                     For <literal>VIA cards</literal>: <ulink url="http://www.viaarena.com/default.aspx?PageID=2">http://www.viaarena.com/default.aspx?PageID=2</ulink>
191                 </para>
192             </listitem>
193         </itemizedlist>
194         <para>Some troubles can also occur when using Windows 2000 (video drivers are no more updated and no more supported).</para>
195         <para>
196             In the cases where pBuffer create a problem, waiting for a working <literal>pbuffer</literal> is not a solution indeed:
197             <ulink url="https://jogl.dev.java.net/issues/show_bug.cgi?id=163">
198                 <emphasis role="italic">The OpenGL community is moving away from pbuffers and toward the frame buffer object extension, which is a more portable and higher-performance solution for offscreen rendering than pbuffers.</emphasis>
199             </ulink>
200             .The JOGL team is working to fix this issue.
201         </para>
202         <para>For more information about this problem, please refer to: </para>
203         <itemizedlist>
204             <listitem>
205                 <para>
206                     <literal>JoGL</literal> bug database: <ulink url="https://jogl.dev.java.net/issues/show_bug.cgi?id=366">Bug #366</ulink>
207                 </para>
208             </listitem>
209             <listitem>
210                 <para>
211                     <literal>Scilab</literal> bug database: <ulink url="http://bugzilla.scilab.org/show_bug.cgi?id=3525">Bug #3525</ulink>
212                 </para>
213             </listitem>
214             <listitem>
215                 <para>
216                     <literal>Debian</literal> bug database: <ulink url="http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=501799">Bug #501799</ulink>
217                 </para>
218             </listitem>
219             <listitem>
220                 <para>
221                     <literal>Freedesktop</literal> bug database: <ulink url="https://bugs.freedesktop.org/show_bug.cgi?id=17603">Bug #17603</ulink>
222                 </para>
223             </listitem>
224         </itemizedlist>
225     </refsection>
226     <refsection>
227         <title>Examples</title>
228         <programlisting role="example"><![CDATA[
229 // Example using GLJPanel (Mixing uicontrols and graphics is available)
230 usecanvas(%F);
231 plot2d();
232 uicontrol("String", "Close the window", "Position", [10 10 100, 25], "Callback", "delete(gcf())");
233 messagebox("You can see the button on the figure.", "Usecanvas example", "info");
234
235 // Example using GLCanvas (Mixing uicontrols and graphics is not available, uicontrols are not visible)
236 usecanvas(%T);
237 plot2d();
238 uicontrol("String", "Close the window", "Position", [10 10 100, 25], "Callback", "delete(gcf())");
239 messagebox("You can''t see any button on the figure.", "Usecanvas example", "info");
240  ]]></programlisting>
241     </refsection>
242 </refentry>