Matplot: handle ARGB data
[scilab.git] / scilab / modules / graphics / help / en_US / 2d_plot / Matplot_properties.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) INRIA - Fabrice Leray
5  *
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at
10  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
11  *
12  -->
13 <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="Matplot_properties">
14     <refnamediv>
15         <refname>Matplot properties</refname>
16         <refpurpose>
17             description of the Matplot entities properties
18         </refpurpose>
19     </refnamediv>
20     <refsection>
21         <title>Description</title>
22         <para>
23             The <literal>Matplot</literal> entity is a leaf of the graphics entities hierarchy. It
24             represents 2D plots of surface using colors and images (see
25             <function>Matplot</function> and <function>Matplot1</function>).
26         </para>
27         <variablelist>
28             <varlistentry>
29                 <term>parent: </term>
30                 <listitem>
31                     <para>
32                         this property contains the handle of the parent. The parent of the
33                         <literal>Matplot</literal> entity should be of the type <literal>"Axes"</literal>.
34                     </para>
35                 </listitem>
36             </varlistentry>
37             <varlistentry>
38                 <term>children: </term>
39                 <listitem>
40                     <para>
41                         this property contains a vector with the <literal>children</literal> of
42                         the handle. However, <literal>Matplot</literal> handles currently do not
43                         have any <literal>children</literal>.
44                     </para>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>visible: </term>
49                 <listitem>
50                     <para>
51                         this field contains the <literal>visible</literal> property value for
52                         the entity. It should be <literal>"on" </literal> or <literal>"off"</literal> .
53                         By default, the plot is visible, the property's value is
54                         <literal>"on"</literal>. If <literal>"off"</literal> the plot is not drawn on the
55                         screen.
56                     </para>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>data: </term>
61                 <listitem>
62                     <para>
63                         this field defines a [<literal>m</literal>x<literal>n</literal>]
64                         <literal>color</literal> data matrix (double, (u)int8, (u)int16, (u)int32) or hypermatrix.
65                         The colors are interpreted according to the image_type property.
66                         The color associated to <literal>color(i,j)</literal> is used do draw a small square
67                         of length 1 with center at location <literal>(x=j,y=(m-i+1))</literal>.
68                     </para>
69                 </listitem>
70             </varlistentry>
71             <varlistentry>
72                 <term>rect: </term>
73                 <listitem>
74                     <para>
75                         this field contains a row-vector defined by <literal>[xmin, ymin, xmax, ymax]</literal>.
76                         It specifies a rectangle in the current scale and the matrix is drawn inside this rectangle.
77                     </para>
78                 </listitem>
79             </varlistentry>
80             <varlistentry>
81                 <term>image_type: </term>
82                 <listitem>
83                     <para>
84                         this field defines the image type. It could be one of the values: "rgb", "rgba", "gray", "index",
85                         "red", "green", "blue", "rgb332", "rgb444", "rgb555", "rgba5551", "argb".
86                     </para>
87                     <para>
88                         Colors are determinated by the data type and by image_type:
89                     </para>
90                     <itemizedlist>
91                         <listitem>
92                             <para>
93                                 When image_type is equal to index, the data are just considered as an index in the colormap.
94                             </para>
95                         </listitem>
96                         <listitem>
97                             <para>
98                                 When image_type is equal to rgb, hypermat of int8 or uint8 will give the RGB components, hypermat of doubles will give normalized RGB components (values between 0 and 1), matrices of int8 or uint8 where number of rows is a multiple of 3 will give the RGB components, matrices of int32 will give RGB colors, matrices of uint32 will give RGBA colors where the alpha channel will be set to 0xFF.
99                             </para>
100                         </listitem>
101                         <listitem>
102                             <para>
103                                 When image_type is equal to rgba, hypermat of int8 or uint8 will give the RGBA components, hypermat of doubles will give normalized RGBA components (values between 0 and 1), matrices of int8 or uint8 where number of rows is a multiple of 4 will give the RGB components, matrices of int32 will give RGBA colors, matrices of uint32 will give RGBA colors.
104                             </para>
105                         </listitem>
106                         <listitem>
107                             <para>
108                                 When image_type is equal to gray, matrices of int8 or uint8 will give Gray level color (R-G-B=GRAY-GRAY-GRAY), for other types, data will be considered as RGB ones and converted into gray colors (0.299*R+0.587*G+0.114*B).
109                             </para>
110                         </listitem>
111                         <listitem>
112                             <para>
113                                 When image_type is equal to red, matrices of int8 or uint8 will give Red level color (R-G-B=RED-00-00), for other types, data will be considered as RGB ones and converted into red colors (a mask is applied to keep the Red component).
114                             </para>
115                         </listitem>
116                         <listitem>
117                             <para>
118                                 When image_type is equal to green, matrices of int8 or uint8 will give Green level color (R-G-B=00-GREEN-00), for other types, data will be considered as RGB ones and converted into green colors (a mask is applied to keep the Green component).
119                             </para>
120                         </listitem>
121                         <listitem>
122                             <para>
123                                 When image_type is equal to blue, matrices of int8 or uint8 will give Blue level color (R-G-B=00-00-BLUE), for other types, data will be considered as RGB ones and converted into blue colors (a mask is applied to keep the Blue component).
124                             </para>
125                         </listitem>
126                         <listitem>
127                             <para>
128                                 When image_type is equal to rgb332, matrices of int8 or uint8 will give RGB colors where R component is wrote on 3 bits, G component on 3 bits and B component on 2 bits. For other data types, RGB (8-8-8) data are converted into RGB (3-3-2).
129                             </para>
130                         </listitem>
131                         <listitem>
132                             <para>
133                                 When image_type is equal to rgb444, matrices of int16 or uint16 will give RGB colors where each components is wrote on 4 bits. For other data types, RGB (8-8-8) data are converted into RGB (4-4-4).
134                             </para>
135                         </listitem>
136                         <listitem>
137                             <para>
138                                 When image_type is equal to rgb555, matrices of int16 or uint16 will give RGB colors where each components is wrote on 5 bits. For other data types, RGB (8-8-8) data are converted into RGB (5-5-5).
139                             </para>
140                         </listitem>
141                         <listitem>
142                             <para>
143                                 When image_type is equal to rgb4444, matrices of int16 or uint16 will give RGBA colors where each components is wrote on 4 bits. For other data types, RGBA (8-8-8-8) data are converted into RGBA (4-4-4-4).
144                             </para>
145                         </listitem>
146                         <listitem>
147                             <para>
148                                 When image_type is equal to rgb5551, matrices of int16 or uint16 will give RGBA colors where each non-alpha components is wrote on 5 bits and the alpha component on 1 bit. For other data types, RGBA (8-8-8-8) data are converted into RGBA (5-5-5-1).
149                             </para>
150                         </listitem>
151                         <listitem>
152                             <para>
153                                 When image_type is equal to argb, hypermat of int8 or uint8 will give the ARGB components, hypermat of doubles will give normalized ARGB components (values between 0 and 1), matrices of int8 or uint8 where number of rows is a multiple of 4 will give the RGB components, matrices of int32 will give ARGB colors, matrices of uint32 will give ARGB colors.
154                             </para>
155                         </listitem>
156                     </itemizedlist>
157                 </listitem>
158             </varlistentry>
159             <varlistentry>
160                 <term>clip_state: </term>
161                 <listitem>
162                     <para>
163                         this field contains the <literal>clip_state</literal> property value for
164                         the <literal>Matplot</literal>. It should be :
165                     </para>
166                     <itemizedlist>
167                         <listitem>
168                             <para>
169                                 <literal>"off"</literal> this means that the <literal>Matplot</literal> is not
170                                 clipped.
171                             </para>
172                         </listitem>
173                         <listitem>
174                             <para>
175                                 <literal>"clipgrf"</literal> this means that the <literal>Matplot</literal> is clipped
176                                 outside the <literal>Axes</literal> box.
177                             </para>
178                         </listitem>
179                         <listitem>
180                             <para>
181                                 <literal>"on"</literal> this means that the <literal>Matplot</literal> is clipped
182                                 outside the rectangle given by property <literal>clip_box</literal>.
183                             </para>
184                         </listitem>
185                     </itemizedlist>
186                 </listitem>
187             </varlistentry>
188             <varlistentry>
189                 <term>clip_box: </term>
190                 <listitem>
191                     <para>
192                         this field is to determinate the <literal>clip_box</literal> property.
193                         By default its value should be an empty matrix if <literal>clip_state</literal> is
194                         <literal>"off"</literal>. Other cases the vector <literal>[x,y,w,h]</literal>
195                         (upper-left point width height) defines the portions of the <literal>Matplot</literal>
196                         to display, however <literal>clip_state</literal> property value will be changed.
197                     </para>
198                 </listitem>
199             </varlistentry>
200             <varlistentry>
201                 <term>user_data: </term>
202                 <listitem>
203                     <para>
204                         this field can be use to store any scilab variable in the
205                         <literal>Matplot</literal> data structure, and to retreive it.
206                     </para>
207                 </listitem>
208             </varlistentry>
209         </variablelist>
210     </refsection>
211     <refsection>
212         <title>Examples</title>
213         <programlisting role="example"><![CDATA[
214 Matplot((1:xget("lastpattern")))
215 e=gce(); // get current entity
216
217 e.data=e.data($:-1:1) // reverse order
218  ]]></programlisting>
219         <scilab:image>
220             Matplot((1:xget("lastpattern")));
221             e=gce();
222             e.data=e.data($:-1:1);
223         </scilab:image>
224     </refsection>
225     <refsection role="see also">
226         <title>See Also</title>
227         <simplelist type="inline">
228             <member>
229                 <link linkend="set">set</link>
230             </member>
231             <member>
232                 <link linkend="get">get</link>
233             </member>
234             <member>
235                 <link linkend="delete">delete</link>
236             </member>
237             <member>
238                 <link linkend="grayplot">grayplot</link>
239             </member>
240             <member>
241                 <link linkend="Matplot">Matplot</link>
242             </member>
243             <member>
244                 <link linkend="Matplot1">Matplot1</link>
245             </member>
246             <member>
247                 <link linkend="graphics_entities">graphics_entities</link>
248             </member>
249             <member>
250                 <link linkend="grayplot_properties">grayplot_properties</link>
251             </member>
252         </simplelist>
253     </refsection>
254     <refsection>
255         <title>History</title>
256         <revhistory>
257             <revision>
258                 <revnumber>5.5.0</revnumber>
259                 <revremark>
260                     Property image_type introduced.
261                 </revremark>
262                 <revremark>
263                     Property rect introduced.
264                 </revremark>
265             </revision>
266         </revhistory>
267     </refsection>
268 </refentry>