407c341e367a6fe8953f9ee3e4f2ad53604f1990
[scilab.git] / scilab / modules / api_scilab / help / en_US / integer_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="Integer_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>Integer writing (Scilab gateway)</refname>
23
24         <refpurpose>
25             How to write matrices of integers in a gateway.
26         </refpurpose>
27     </refnamediv>
28     <refsection>
29         <title>Description</title>
30         <para>This help describes how matrix of integers 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 createMatrixOfInteger8(int _iVar, int _iRows, int _iCols, char* _pcData8)
37 int createMatrixOfInteger16(int _iVar, int _iRows, int _iCols, short* _psData16)
38 int createMatrixOfInteger32(int _iVar, int _iRows, int _iCols, int* _piData32)
39 int createMatrixOfUnsignedInteger8(int _iVar, int _iRows, int _iCols, unsigned char* _pucData8)
40 int createMatrixOfUnsignedInteger16(int _iVar, int _iRows, int _iCols, unsigned short* _pusData16)
41 int createMatrixOfUnsignedInteger32(int _iVar, int _iRows, int _iCols, unsigned int* _puiData32)
42 ]]></programlisting>
43     </refsection>
44     <refsection>
45         <title>Parameters</title>
46
47         <variablelist>
48             <varlistentry>
49                 <term>_iVar</term>
50                 <listitem>
51                     <para>
52                         Position in the Scilab memory where you want to put the variable
53                     </para>
54                 </listitem>
55             </varlistentry>
56
57             <varlistentry>
58                 <term>_iRows</term>
59                 <listitem>
60                     <para>
61                         Number of rows of the new variable
62                     </para>
63                 </listitem>
64             </varlistentry>
65
66             <varlistentry>
67                 <term>_iCols</term>
68                 <listitem>
69                     <para>
70                         Numbers of columns of the new variable
71                     </para>
72                 </listitem>
73             </varlistentry>
74             <varlistentry>
75                 <term>_pcData8, _psData16, _piData32, _pucData8, _pusData16, _puiData32</term>
76                 <listitem>
77                     <para>
78                         Address of data array (size: _iCols * _iRows)
79                     </para>
80                 </listitem>
81             </varlistentry>
82         </variablelist>
83     </refsection>
84     <refsection>
85         <title>Write directly in Scilab memory</title>
86         <programlisting><![CDATA[
87 int allocMatrixOfInteger8(int _iVar, int _iRows, int _iCols, char** _pcData8)
88 int allocMatrixOfInteger16(int _iVar, int _iRows, int _iCols, short** _psData16)
89 int allocMatrixOfInteger32(int _iVar, int _iRows, int _iCols, int** _piData32)
90 int allocMatrixOfUnsignedInteger8(int _iVar, int _iRows, int _iCols, unsigned char** _pucData8)
91 int allocMatrixOfUnsignedInteger16(int _iVar, int _iRows, int _iCols, unsigned short** _pusData16)
92 int allocMatrixOfUnsignedInteger32(int _iVar, int _iRows, int _iCols, unsigned int** _puiData32)
93 ]]></programlisting>
94     </refsection>
95     <refsection>
96         <title>Parameters</title>
97         <variablelist>
98             <varlistentry>
99                 <term>_iVar</term>
100                 <listitem>
101                     <para>
102                         Position in the Scilab memory where you want to put the variable
103                     </para>
104                 </listitem>
105             </varlistentry>
106             <varlistentry>
107                 <term>_iRows</term>
108                 <listitem>
109                     <para>
110                         Number of rows of the new variable
111                     </para>
112                 </listitem>
113             </varlistentry>
114             <varlistentry>
115                 <term>_iCols</term>
116                 <listitem>
117                     <para>
118                         Numbers of columns of the new variable
119                     </para>
120                 </listitem>
121             </varlistentry>
122             <varlistentry>
123                 <term>_pcData8, _psData16, _piData32, _pucData8, _pusData16, _puiData32</term>
124                 <listitem>
125                     <para>
126                         Returns address of data array (size: _iCols * _iRows)
127                     </para>
128                 </listitem>
129             </varlistentry>
130         </variablelist>
131     </refsection>
132
133     <refsection>
134         <!--File_gateway: SCI/modules/api_scilab/tests/unit_tests/integer_writing_api.c-->
135         <!--File_scilab: SCI/modules/api_scilab/tests/unit_tests/integer_writing_api.tst-->
136         <!--Lib_name: integer_writing-->
137         <!--Func_list: write_integer-->
138         <title>Gateway Source</title>
139         <programlisting role="code_gateway">
140             <![CDATA[
141 void* create_output(int _iCoeff, int _iSize, int _iRows, int _iCols, void* _pvDataIn);
142
143 int read_integer(char *fname,unsigned long fname_len)
144 {
145     int iRet                    = 0;
146
147     //output variable info
148     int iRows8                  = 0;
149     int iCols8                  = 0;
150     int iRows16                 = 0;
151     int iCols16                 = 0;
152     int iRows32                 = 0;
153     int iCols32                 = 0;
154     int iRowsu8                 = 0;
155     int iColsu8                 = 0;
156     int iRowsu16                = 0;
157     int iColsu16                = 0;
158     int iRowsu32                = 0;
159     int iColsu32                = 0;
160     int iPrec                   = 0;
161
162     int* piAddr8                = NULL;
163     int* piAddr16               = NULL;
164     int* piAddr32               = NULL;
165     int* piAddru8               = NULL;
166     int* piAddru16              = NULL;
167     int* piAddru32              = NULL;
168
169     char* pcData                = NULL;
170     short* psData               = NULL;
171     int* piData                 = NULL;
172     unsigned char* pucData      = NULL;
173     unsigned short* pusData     = NULL;
174     unsigned int* puiData       = NULL;
175
176     char* pcDataOut             = NULL;
177     short* psDataOut            = NULL;
178     int* piDataOut              = NULL;
179     unsigned char* pucDataOut   = NULL;
180     unsigned short* pusDataOut  = NULL;
181     unsigned int* puiDataOut    = NULL;
182
183     //check input/ouput arguments count
184     CheckRhs(6,6);
185     CheckLhs(6,6);
186
187     //get varialbe address
188     getVarAddressFromPosition(1, &piAddr8);
189     getVarAddressFromPosition(2, &piAddru8);
190     getVarAddressFromPosition(3, &piAddr16);
191     getVarAddressFromPosition(4, &piAddru16);
192     getVarAddressFromPosition(5, &piAddr32);
193     getVarAddressFromPosition(6, &piAddru32);
194
195     //check variable precision
196     iRet = getMatrixOfIntegerPrecision(piAddr8, &iPrec);
197     if(iPrec != SCI_INT8)
198     {
199         return 1;
200     }
201
202     //check variable precision
203     iRet = getMatrixOfIntegerPrecision(piAddru8, &iPrec);
204     if(iPrec != SCI_UINT8)
205     {
206         return 1;
207     }
208
209     //check variable precision
210     iRet = getMatrixOfIntegerPrecision(piAddr16, &iPrec);
211     if(iPrec != SCI_INT16)
212     {
213         return 1;
214     }
215
216     //check variable precision
217     iRet = getMatrixOfIntegerPrecision(piAddru16, &iPrec);
218     if(iPrec != SCI_UINT16)
219     {
220         return 1;
221     }
222
223     //check variable precision
224     iRet = getMatrixOfIntegerPrecision(piAddr32, &iPrec);
225     if(iPrec != SCI_INT32)
226     {
227         return 1;
228     }
229
230     //check variable precision
231     iRet = getMatrixOfIntegerPrecision(piAddru32, &iPrec);
232     if(iPrec != SCI_UINT32)
233     {
234         return 1;
235     }
236
237     //retrieve dimensions and data
238     iRet = getMatrixOfInteger8(piAddr8, &iRows8, &iCols8, &pcData);
239     if(iRet)
240     {
241         return 1;
242     }
243
244     //retrieve dimensions and data
245     iRet = getMatrixOfUnsignedInteger8(piAddru8, &iRowsu8, &iColsu8, &pucData);
246     if(iRet)
247     {
248         return 1;
249     }
250
251     //retrieve dimensions and data
252     iRet = getMatrixOfInteger16(piAddr16, &iRows16, &iCols16, &psData);
253     if(iRet)
254     {
255         return 1;
256     }
257
258     //retrieve dimensions and data
259     iRet = getMatrixOfUnsignedInteger16(piAddru16, &iRowsu16, &iColsu16, &pusData);
260     if(iRet)
261     {
262         return 1;
263     }
264
265     //retrieve dimensions and data
266     iRet = getMatrixOfInteger32(piAddr32, &iRows32, &iCols32, &piData);
267     if(iRet)
268     {
269         return 1;
270     }
271
272     //retrieve dimensions and data
273     iRet = getMatrixOfUnsignedInteger32(piAddru32, &iRowsu32, &iColsu32, &puiData);
274     if(iRet)
275     {
276         return 1;
277     }
278
279     //alloc and fill new variable
280     pcDataOut   = (char*)create_output(2, 1, iRows8, iCols8, (void*)pcData);
281     pucDataOut  = (unsigned char*)create_output(4, 1, iRowsu8, iColsu8, (void*)pucData);
282     psDataOut   = (short*)create_output(8, 2, iRows16, iCols16, (void*)psData);
283     pusDataOut  = (unsigned short*)create_output(16, 2, iRowsu16, iColsu16, (void*)pusData);
284     piDataOut   = (int*)create_output(32, 4, iRows32, iCols32, (void*)piData);
285     puiDataOut  = (unsigned int*)create_output(64, 4, iRowsu32, iColsu32, (void*)puiData);
286
287     //create new variable
288     iRet = createMatrixOfInteger8(Rhs + 1, iRows8, iCols8, pcDataOut);
289     if(iRet)
290     {
291         return 1;
292     }
293
294     //create new variable
295     iRet = createMatrixOfUnsignedInteger8(Rhs + 2, iRowsu8, iColsu8, pucDataOut);
296     if(iRet)
297     {
298         return 1;
299     }
300
301     //create new variable
302     iRet = createMatrixOfInteger16(Rhs + 3, iRows16, iCols16, psDataOut);
303     if(iRet)
304     {
305         return 1;
306     }
307
308     //create new variable
309     iRet = createMatrixOfUnsignedInteger16(Rhs + 4, iRowsu16, iColsu16, pusDataOut);
310     if(iRet)
311     {
312         return 1;
313     }
314
315     //create new variable
316     iRet = createMatrixOfInteger32(Rhs + 5, iRows32, iCols32, piDataOut);
317     if(iRet)
318     {
319         return 1;
320     }
321
322     //create new variable
323     iRet = createMatrixOfUnsignedInteger32(Rhs + 6, iRowsu32, iColsu32, puiDataOut);
324     if(iRet)
325     {
326         return 1;
327     }
328
329     //assign allocated variables to Lhs position
330     LhsVar(1) = Rhs + 1;
331     LhsVar(2) = Rhs + 2;
332     LhsVar(3) = Rhs + 3;
333     LhsVar(4) = Rhs + 4;
334     LhsVar(5) = Rhs + 5;
335     LhsVar(6) = Rhs + 6;
336     PutLhsVar();
337     return 0;
338 }
339
340 void* create_output(int _iCoeff, int _iSize, int _iRows, int _iCols, void* _pvDataIn)
341 {
342     int i = 0;
343     void* pvDataOut = (void*)malloc(_iSize * _iRows * _iCols);
344     for(i = 0 ; i < _iRows * _iCols ; i++)
345     {
346         int iVal = 0;
347         memcpy(&iVal, (char*)_pvDataIn + i * _iSize, _iSize);
348         iVal *= _iCoeff;
349         memcpy((char*)pvDataOut + i * _iSize, &iVal, _iSize);
350     }
351     return pvDataOut;
352 }
353             ]]>
354         </programlisting>
355     </refsection>
356
357     <refsection>
358         <title>Scilab test script</title>
359         <programlisting role="code_scilab">
360             <![CDATA[
361 a8  = int8([    1   -2  3   -4  5; ..
362                 -6  7   -8  9   -10; ..
363                 11  -12 13  -14 15]);
364
365 au8 = uint8([   1   2   3   4   5; ..
366                 6   7   8   9   10; ..
367                 11  12  13  14  15]);
368
369 a16  = int16([  1   -2  3   -4  5; ..
370                 -6  7   -8  9   -10; ..
371                 11  -12 13  -14 15]);
372
373 au16 = uint16([ 1   2   3   4   5; ..
374                 6   7   8   9   10; ..
375                 11  12  13  14  15]);
376
377 a32 = int32([   1   -2  3   -4  5; ..
378                 -6  7   -8  9   -10; ..
379                 11  -12 13  -14 15]);
380
381 au32 = uint32([ 1   2   3   4   5; ..
382                 6   7   8   9   10; ..
383                 11  12  13  14  15]);
384
385 [c8, cu8, c16, cu16, c32, cu32] = tonio(a8, au8, a16, au16, a32, au32);
386
387 if or(c8 <> a8 * 2) then error("failed"), end
388 if or(cu8 <> au8 * 4) then error("failed"), end
389 if or(c16 <> a16 * 8) then error("failed"), end
390 if or(cu16 <> au16 * 16) then error("failed"), end
391 if or(c32 <> a32 * 32) then error("failed"), end
392 if or(cu32 <> au32 * 64) then error("failed"), end
393             ]]>
394         </programlisting>
395     </refsection>
396 </refentry>