141d72c9145c08f4ba132ddbd4c0786dc6e60960
[scilab.git] / scilab / modules / api_scilab / help / en_US / double_writing_api.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) 2009  - DIGITEO - Antoine ELIAS
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-en.txt
11  *
12  -->
13 <refentry version="5.0-subset Scilab" xml:id="Double_management_writing_API"
14           xml:lang="en" xmlns="http://docbook.org/ns/docbook"
15           xmlns:xlink="http://www.w3.org/1999/xlink"
16           xmlns:svg="http://www.w3.org/2000/svg"
17           xmlns:ns5="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML"
19           xmlns:db="http://docbook.org/ns/docbook">
20
21     <refnamediv>
22         <refname>Double writing (Scilab gateway)</refname>
23
24         <refpurpose>
25             How to write matrices of doubles in a gateway.
26         </refpurpose>
27     </refnamediv>
28     <refsection>
29         <title>Description</title>
30         <para>This help describes how matrix of doubles can be handled through the Scilab API.</para>
31         <para>There are 2 types of functions which can be used to write in the memory of Scilab.</para>
32     </refsection>
33     <refsection>
34         <title>Create from existing data</title>
35         <programlisting><![CDATA[
36 int createMatrixOfDouble(int _iVar, int _iRows, int _iCols, double* _pdblReal)
37 int createComplexMatrixOfDouble(int _iVar, int _iRows, int _iCols, double* _pdblReal, double* _pdblImg)
38 ]]></programlisting>
39     </refsection>
40     <refsection>
41         <title>Parameters</title>
42         <variablelist>
43             <varlistentry>
44                 <term>_iVar</term>
45                 <listitem>
46                     <para>
47                         Position in the Scilab memory where you want to put the variable
48                     </para>
49                 </listitem>
50             </varlistentry>
51             <varlistentry>
52                 <term>_iRows</term>
53                 <listitem>
54                     <para>
55                         Number of rows of the new variable
56                     </para>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>_iCols</term>
61                 <listitem>
62                     <para>
63                         Numbers of columns of the new variable
64                     </para>
65                 </listitem>
66             </varlistentry>
67             <varlistentry>
68                 <term>_pdblReal</term>
69                 <listitem>
70                     <para>
71                         Address of real data array (size: _iCols * _iRows)
72                     </para>
73                 </listitem>
74             </varlistentry>
75             <varlistentry>
76                 <term>_pdblImg</term>
77                 <listitem>
78                     <para>
79                         Address of imaginary data array (size: _iCols * _iRows)
80                     </para>
81                 </listitem>
82             </varlistentry>
83         </variablelist>
84     </refsection>
85     <refsection>
86         <title>Write directly in Scilab memory</title>
87         <programlisting><![CDATA[
88 int allocMatrixOfDouble(int _iVar, int _iRows, int _iCols, double** _pdblReal)
89 int allocComplexMatrixOfDouble(int _iVar, int _iRows, int _iCols, double** _pdblReal, double** _pdblImg)
90 ]]></programlisting>
91     </refsection>
92     <refsection>
93         <title>Parameters</title>
94         <variablelist>
95             <varlistentry>
96                 <term>_iVar</term>
97                 <listitem>
98                     <para>
99                         Position in the Scilab memory where you want to put the variable
100                     </para>
101                 </listitem>
102             </varlistentry>
103             <varlistentry>
104                 <term>_iRows</term>
105                 <listitem>
106                     <para>
107                         Number of rows of the new variable
108                     </para>
109                 </listitem>
110             </varlistentry>
111             <varlistentry>
112                 <term>_iCols</term>
113                 <listitem>
114                     <para>
115                         Numbers of columns of the new variable
116                     </para>
117                 </listitem>
118             </varlistentry>
119             <varlistentry>
120                 <term>_pdblReal</term>
121                 <listitem>
122                     <para>
123                         Returns address of real data array (size: _iCols * _iRows)
124                     </para>
125                 </listitem>
126             </varlistentry>
127             <varlistentry>
128                 <term>_pdblImg</term>
129                 <listitem>
130                     <para>
131                         Returns address of imaginary data array (size: _iCols * _iRows)
132                     </para>
133                 </listitem>
134             </varlistentry>
135         </variablelist>
136     </refsection>
137     <refsection>
138         <!--File_gateway: SCI/modules/api_scilab/tests/unit_tests/double_writing_api.c-->
139         <!--File_scilab: SCI/modules/api_scilab/tests/unit_tests/double_writing_api.tst-->
140         <!--Lib_name: double_writing-->
141         <!--Func_list: write_double-->
142         <title>Gateway Source</title>
143         <programlisting role="code_gateway">
144             <![CDATA[
145 int write_double(char *fname,unsigned long fname_len)
146 {
147     int i,j;
148     int iRet            = 0;
149     //first variable info : real matrix of double 3 x 4
150     int iRows1          = 3;
151     int iCols1          = 4;
152     double* pdblReal1   = NULL;
153
154     //second variable info : complex matrix of double 4 x 6
155     int iRows2          = 4;
156     int iCols2          = 6;
157     double* pdblReal2   = NULL;
158     double* pdblImg2    = NULL;
159
160     /************************
161     *    First variable    *
162     ************************/
163     //alloc array of data in OS memory
164     pdblReal1 = (double*)malloc(sizeof(double) * iRows1 * iCols1);
165
166     //fill array with incremental values
167     //[ 0   1   2   3
168     //  4   5   6   7
169     //  8   9   10  11]
170     for(i = 0 ; i < iRows1 ; i++)
171     {
172         for(j = 0 ; j < iCols1 ; j++)
173         {
174             pdblReal1[i + iRows1 * j] = i * iCols1 + j;
175         }
176     }
177     //can be written in a single loop
178     //for(i = 0 ; i < iRows1 * iCols1; i++)
179     //{
180     //  pdblReal1[i] = i;
181     //}
182
183     //create a variable from a existing data array
184     iRet = createMatrixOfDouble(Rhs + 1, iRows1, iCols1, pdblReal1);
185     if(iRet)
186     {
187         //Error
188         return 1;
189     }
190
191     //after creation, we can free memory.
192     free(pdblReal1);
193     /*************************
194     *    Second variable    *
195     *************************/
196
197     //reserve space in scilab memory and fill it
198     iRet = allocComplexMatrixOfDouble(Rhs + 2, iRows2, iCols2, &pdblReal2, &pdblImg2);
199     if(iRet)
200     {
201         //Error
202         return 1;
203     }
204
205     //fill array with incremental values for real part and decremental for imaginary part
206     //[ 23i     1+22i       2+21i       3+20i       4+19i       5+18i
207     //  6+17i   7+16i       8+15i       9+14i       10+13i      11+12i
208     //  12+11i  13+10i      14+9i       15+8i       16+7i       17+6i
209     //  18+5i   19+4i       20+3i       21+2i       22+1i       23  ]
210     for(i = 0 ; i < iRows2 ; i++)
211     {
212        for(j = 0 ; j < iCols2 ; j++)
213         {
214             pdblReal2[i + iRows2 * j] = i * iCols2 + j;
215             pdblImg2 [i + iRows2 * j]   = (iRows2 * iCols2 - 1) - (i * iCols2 + j);
216         }
217     }
218     //can be written in a single loop
219     //for(i = 0 ; i < iRows2 * iCols2; i++)
220     //{
221     //  pdblReal2[i] = i;
222     //  pdblImg2 [i] = (iRows2 * iCols2 - 1) - i;
223     //}
224
225     // /!\ DO NOT FREE MEMORY, in this case, it's the Scilab memory
226
227
228     //assign allocated variables to Lhs position
229     LhsVar(1) = Rhs + 1;
230     LhsVar(2) = Rhs + 2;
231     return 0;
232 }
233         ]]>
234         </programlisting>
235     </refsection>
236     <refsection>
237         <title>Scilab test script</title>
238         <programlisting role="code_scilab">
239             <![CDATA[
240 a_ref = [   0 1 2 3; ..
241             4 5 6 7; ..
242             8 9 10 11];
243 b_ref = [   23*%i,      1+22*%i,    2+21*%i,    3+20*%i,    4+19*%i,    5+18*%i; ..
244             6+17*%i,    7+16*%i,    8+15*%i,    9+14*%i,     10+13*%i,  11+12*%i; ..
245             12+11*%i,   13+10*%i,   14+9*%i,    15+8*%i,    16+7*%i,    17+6*%i; ..
246             18+5*%i,    19+4*%i,    20+3*%i,    21+2*%i,    22+1*%i,    23];
247 [a,b] = write_double();
248 if or(a <> a_ref) then error("failed");end
249 if or(b <>; b_ref) then error("failed");end
250             ]]>
251         </programlisting>
252     </refsection>
253 </refentry>