License Header change: Removed the LICENSE_END before beta
[scilab.git] / scilab / modules / api_scilab / help / en_US / legacy / low_level_functions / 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  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="Integer_management_writing_API" xml:lang="en">
17     <refnamediv>
18         <refname>Integer writing (Scilab gateway)</refname>
19         <refpurpose>
20             How to write matrices of integers in a gateway.
21         </refpurpose>
22     </refnamediv>
23     <refsynopsisdiv>
24         <refsection>
25             Create from existing data.
26         </refsection>
27         <title>Calling Sequence</title>
28         <para>Input argument profile:</para>
29         <para>Signed integer :</para>
30         <synopsis>SciErr createMatrixOfInteger8(void* _pvCtx, int _iVar, int _iRows, int _iCols, const char* _pcData8)</synopsis>
31         <synopsis>SciErr createMatrixOfInteger16(void* _pvCtx, int _iVar, int _iRows, int _iCols, const short* _psData16)</synopsis>
32         <synopsis>SciErr createMatrixOfInteger32(void* _pvCtx, int _iVar, int _iRows, int _iCols, const int* _piData32)</synopsis>
33         <para>Unsigned integer :</para>
34         <synopsis>SciErr createMatrixOfUnsignedInteger8(void* _pvCtx, int _iVar, int _iRows, int _iCols, const unsigned char* _pucData8)</synopsis>
35         <synopsis>SciErr createMatrixOfUnsignedInteger16(void* _pvCtx, int _iVar, int _iRows, int _iCols, const unsigned short* _pusData16)</synopsis>
36         <synopsis>SciErr createMatrixOfUnsignedInteger32(void* _pvCtx, int _iVar, int _iRows, int _iCols, const unsigned int* _puiData32)</synopsis>
37         <para>Named variable profile:</para>
38         <para>Signed integer :</para>
39         <synopsis>SciErr createNamedMatrixOfInteger8(void* _pvCtx, const char* _pstName, int _iRows, int _iCols, const char* _pcData8)</synopsis>
40         <synopsis>SciErr createNamedMatrixOfInteger16(void* _pvCtx, const char* _pstName, int _iRows, int _iCols, const short* _psData16)</synopsis>
41         <synopsis>SciErr createNamedMatrixOfInteger32(void* _pvCtx, const char* _pstName, int _iRows, int _iCols, const int* _piData32)</synopsis>
42         <para>Unsigned integer :</para>
43         <synopsis>SciErr createNamedMatrixOfUnsignedInteger8(void* _pvCtx, const char* _pstName, int _iRows, int _iCols, const unsigned char* _pucData8)</synopsis>
44         <synopsis>SciErr createNamedMatrixOfUnsignedInteger16(void* _pvCtx, const char* _pstName, int _iRows, int _iCols, const unsigned short* _pusData16)</synopsis>
45         <synopsis>SciErr createNamedMatrixOfUnsignedInteger32(void* _pvCtx, const char* _pstName, int _iRows, int _iCols, const unsigned int* _puiData32)</synopsis>
46     </refsynopsisdiv>
47     <refsection>
48         <title>Arguments</title>
49         <variablelist>
50             <varlistentry>
51                 <term>_pvCtx</term>
52                 <listitem>
53                     <para>
54                         Scilab environment pointer, pass in "pvApiCtx" provided by api_scilab.h.
55                     </para>
56                 </listitem>
57             </varlistentry>
58             <varlistentry>
59                 <term>_iVar</term>
60                 <listitem>
61                     <para>
62                         Position in the Scilab memory where you want to put the variable
63                     </para>
64                 </listitem>
65             </varlistentry>
66             <varlistentry>
67                 <term>_pstName</term>
68                 <listitem>
69                     <para>
70                         Name of the variable for "named" functions.
71                     </para>
72                 </listitem>
73             </varlistentry>
74             <varlistentry>
75                 <term>_iRows</term>
76                 <listitem>
77                     <para>
78                         Number of rows of the new variable
79                     </para>
80                 </listitem>
81             </varlistentry>
82             <varlistentry>
83                 <term>_iCols</term>
84                 <listitem>
85                     <para>
86                         Numbers of columns of the new variable
87                     </para>
88                 </listitem>
89             </varlistentry>
90             <varlistentry>
91                 <term>_pcData8, _psData16, _piData32, _pucData8, _pusData16, _puiData32</term>
92                 <listitem>
93                     <para>
94                         Address of data array (size: _iCols * _iRows)
95                     </para>
96                 </listitem>
97             </varlistentry>
98             <varlistentry>
99                 <term>SciErr</term>
100                 <listitem>
101                     <para>
102                         Error structure where is stored errors messages history and first error number.
103                     </para>
104                 </listitem>
105             </varlistentry>
106         </variablelist>
107     </refsection>
108     <refsynopsisdiv>
109         <refsection>
110             Write directly in Scilab memory.
111         </refsection>
112         <title>Calling Sequence</title>
113         <para>Input argument profile:</para>
114         <para>Signed integer :</para>
115         <synopsis>SciErr allocMatrixOfInteger8(void* _pvCtx, int _iVar, int _iRows, int _iCols, char** _pcData8)</synopsis>
116         <synopsis>SciErr allocMatrixOfInteger16(void* _pvCtx, int _iVar, int _iRows, int _iCols, short** _psData16)</synopsis>
117         <synopsis>SciErr allocMatrixOfInteger32(void* _pvCtx, int _iVar, int _iRows, int _iCols, int** _piData32)</synopsis>
118         <para>Unsigned integer :</para>
119         <synopsis>SciErr allocMatrixOfUnsignedInteger8(void* _pvCtx, int _iVar, int _iRows, int _iCols, unsigned char** _pucData8)</synopsis>
120         <synopsis>SciErr allocMatrixOfUnsignedInteger16(void* _pvCtx, int _iVar, int _iRows, int _iCols, unsigned short** _pusData16)</synopsis>
121         <synopsis>SciErr allocMatrixOfUnsignedInteger32(void* _pvCtx, int _iVar, int _iRows, int _iCols, unsigned int** _puiData32)</synopsis>
122     </refsynopsisdiv>
123     <refsection>
124         <title>Arguments</title>
125         <variablelist>
126             <varlistentry>
127                 <term>_pvCtx</term>
128                 <listitem>
129                     <para>
130                         Scilab environment pointer, pass in "pvApiCtx" provided by api_scilab.h.
131                     </para>
132                 </listitem>
133             </varlistentry>
134             <varlistentry>
135                 <term>_iVar</term>
136                 <listitem>
137                     <para>
138                         Position in the Scilab memory where you want to put the variable
139                     </para>
140                 </listitem>
141             </varlistentry>
142             <varlistentry>
143                 <term>_iRows</term>
144                 <listitem>
145                     <para>
146                         Number of rows of the new variable
147                     </para>
148                 </listitem>
149             </varlistentry>
150             <varlistentry>
151                 <term>_iCols</term>
152                 <listitem>
153                     <para>
154                         Numbers of columns of the new variable
155                     </para>
156                 </listitem>
157             </varlistentry>
158             <varlistentry>
159                 <term>_pcData8, _psData16, _piData32, _pucData8, _pusData16, _puiData32</term>
160                 <listitem>
161                     <para>
162                         Returns address of data array (size: _iCols * _iRows)
163                     </para>
164                 </listitem>
165             </varlistentry>
166             <varlistentry>
167                 <term>SciErr</term>
168                 <listitem>
169                     <para>
170                         Error structure where is stored errors messages history and first error number.
171                     </para>
172                 </listitem>
173             </varlistentry>
174         </variablelist>
175     </refsection>
176     <refsection>
177         <title>Description</title>
178         <para>This help describes how matrix of integers can be handled through the Scilab API.</para>
179         <para>Two types of functions can be used to write in the memory of Scilab.</para>
180     </refsection>
181     <refsection>
182         <!--File_gateway: SCI/modules/api_scilab/tests/unit_tests/integer_writing_api.c-->
183         <!--File_scilab: SCI/modules/api_scilab/tests/unit_tests/integer_writing_api.tst-->
184         <!--Lib_name: integer_writing-->
185         <!--Func_list: read_integer-->
186         <title>Gateway Source</title>
187         <programlisting role="code_gateway"><![CDATA[ 
188 #include "api_scilab.h"
189 void* create_output(int _iCoeff, int _iSize, int _iRows, int _iCols, void* _pvDataIn);
190
191 int read_integer(char *fname,void* pvApiCtx)
192 {
193         SciErr sciErr;
194         //output variable info
195         int iRows8                                      = 0;
196         int iCols8                                      = 0;
197         int iRows16                                     = 0;
198         int iCols16                                     = 0;
199         int iRows32                                     = 0;
200         int iCols32                                     = 0;
201         int iRowsu8                                     = 0;
202         int iColsu8                                     = 0;
203         int iRowsu16                            = 0;
204         int iColsu16                            = 0;
205         int iRowsu32                            = 0;
206         int iColsu32                            = 0;
207         int iPrec                                       = 0;
208         int* piAddr8                            = NULL;
209         int* piAddr16                           = NULL;
210         int* piAddr32                           = NULL;
211         int* piAddru8                           = NULL;
212         int* piAddru16                          = NULL;
213         int* piAddru32                          = NULL;
214         char* pcData                            = NULL;
215         short* psData                           = NULL;
216         int* piData                                     = NULL;
217         unsigned char* pucData          = NULL;
218         unsigned short* pusData         = NULL;
219         unsigned int* puiData           = NULL;
220         char* pcDataOut                         = NULL;
221         short* psDataOut                        = NULL;
222         int* piDataOut                          = NULL;
223         unsigned char* pucDataOut       = NULL;
224         unsigned short* pusDataOut      = NULL;
225         unsigned int* puiDataOut        = NULL;
226
227         //check input/output arguments count
228     CheckInputArgument(pvApiCtx, 6, 6);
229     CheckOutputArgument(pvApiCtx, 6, 6);
230
231         //get variable address
232         sciErr = getVarAddressFromPosition(pvApiCtx, 1, &piAddr8);
233         if(sciErr.iErr)
234         {
235                 printError(&sciErr, 0);
236                 return 0;
237         }
238
239         sciErr = getVarAddressFromPosition(pvApiCtx, 2, &piAddru8);
240         if(sciErr.iErr)
241         {
242                 printError(&sciErr, 0);
243                 return 0;
244         }
245
246         sciErr = getVarAddressFromPosition(pvApiCtx, 3, &piAddr16);
247         if(sciErr.iErr)
248         {
249                 printError(&sciErr, 0);
250                 return 0;
251         }
252
253         sciErr = getVarAddressFromPosition(pvApiCtx, 4, &piAddru16);
254         if(sciErr.iErr)
255         {
256                 printError(&sciErr, 0);
257                 return 0;
258         }
259
260         sciErr = getVarAddressFromPosition(pvApiCtx, 5, &piAddr32);
261         if(sciErr.iErr)
262         {
263                 printError(&sciErr, 0);
264                 return 0;
265         }
266
267         sciErr = getVarAddressFromPosition(pvApiCtx, 6, &piAddru32);
268         if(sciErr.iErr)
269         {
270                 printError(&sciErr, 0);
271                 return 0;
272         }
273
274         //check variable precision
275         sciErr = getMatrixOfIntegerPrecision(pvApiCtx, piAddr8, &iPrec);
276         if(sciErr.iErr || iPrec != SCI_INT8)
277         {
278                 printError(&sciErr, 0);
279                 return 0;
280         }
281
282         //check variable precision
283         sciErr = getMatrixOfIntegerPrecision(pvApiCtx, piAddru8, &iPrec);
284         if(sciErr.iErr || iPrec != SCI_UINT8)
285         {
286                 printError(&sciErr, 0);
287                 return 0;
288         }
289
290         //check variable precision
291         sciErr = getMatrixOfIntegerPrecision(pvApiCtx, piAddr16, &iPrec);
292         if(sciErr.iErr || iPrec != SCI_INT16)
293         {
294                 printError(&sciErr, 0);
295                 return 0;
296         }
297
298         //check variable precision
299         sciErr = getMatrixOfIntegerPrecision(pvApiCtx, piAddru16, &iPrec);
300         if(sciErr.iErr || iPrec != SCI_UINT16)
301         {
302                 printError(&sciErr, 0);
303                 return 0;
304         }
305         //check variable precision
306         sciErr = getMatrixOfIntegerPrecision(pvApiCtx, piAddr32, &iPrec);
307         if(sciErr.iErr || iPrec != SCI_INT32)
308         {
309                 printError(&sciErr, 0);
310                 return 0;
311         }
312
313         //check variable precision
314         sciErr = getMatrixOfIntegerPrecision(pvApiCtx, piAddru32, &iPrec);
315         if(sciErr.iErr || iPrec != SCI_UINT32)
316         {
317                 printError(&sciErr, 0);
318                 return 0;
319         }
320
321         //retrieve dimensions and data
322         sciErr = getMatrixOfInteger8(pvApiCtx, piAddr8, &iRows8, &iCols8, &pcData);
323         if(sciErr.iErr)
324         {
325                 printError(&sciErr, 0);
326                 return 0;
327         }
328
329         //retrieve dimensions and data
330         sciErr = getMatrixOfUnsignedInteger8(pvApiCtx, piAddru8, &iRowsu8, &iColsu8, &pucData);
331         if(sciErr.iErr)
332         {
333                 printError(&sciErr, 0);
334                 return 0;
335         }
336
337         //retrieve dimensions and data
338         sciErr = getMatrixOfInteger16(pvApiCtx, piAddr16, &iRows16, &iCols16, &psData);
339         if(sciErr.iErr)
340         {
341                 printError(&sciErr, 0);
342                 return 0;
343         }
344
345         //retrieve dimensions and data
346         sciErr = getMatrixOfUnsignedInteger16(pvApiCtx, piAddru16, &iRowsu16, &iColsu16, &pusData);
347         if(sciErr.iErr)
348         {
349                 printError(&sciErr, 0);
350                 return 0;
351         }
352
353         //retrieve dimensions and data
354         sciErr = getMatrixOfInteger32(pvApiCtx, piAddr32, &iRows32, &iCols32, &piData);
355         if(sciErr.iErr)
356         {
357                 printError(&sciErr, 0);
358                 return 0;
359         }
360
361         //retrieve dimensions and data
362         sciErr = getMatrixOfUnsignedInteger32(pvApiCtx, piAddru32, &iRowsu32, &iColsu32, &puiData);
363         if(sciErr.iErr)
364         {
365                 printError(&sciErr, 0);
366                 return 0;
367         }
368
369         //alloc and fill new variable
370         pcDataOut   = (char*)create_output(2, 1, iRows8, iCols8, (void*)pcData);
371         pucDataOut  = (unsigned char*)create_output(4, 1, iRowsu8, iColsu8, (void*)pucData);
372         psDataOut   = (short*)create_output(8, 2, iRows16, iCols16, (void*)psData);
373         pusDataOut  = (unsigned short*)create_output(16, 2, iRowsu16, iColsu16, (void*)pusData);
374         piDataOut   = (int*)create_output(32, 4, iRows32, iCols32, (void*)piData);
375         puiDataOut  = (unsigned int*)create_output(64, 4, iRowsu32, iColsu32, (void*)puiData);
376
377         //create new variable
378         sciErr = createMatrixOfInteger8(pvApiCtx, nbInputArgument(pvApiCtx) + 1, iRows8, iCols8, pcDataOut);
379         if(sciErr.iErr)
380         {
381                 printError(&sciErr, 0);
382                 return 0;
383         }
384
385         //create new variable
386         sciErr = createMatrixOfUnsignedInteger8(pvApiCtx, nbInputArgument(pvApiCtx) + 2, iRowsu8, iColsu8, pucDataOut);
387         if(sciErr.iErr)
388         {
389                 printError(&sciErr, 0);
390                 return 0;
391         }
392
393         //create new variable
394         sciErr = createMatrixOfInteger16(pvApiCtx, nbInputArgument(pvApiCtx) + 3, iRows16, iCols16, psDataOut);
395         if(sciErr.iErr)
396         {
397                 printError(&sciErr, 0);
398                 return 0;
399         }
400
401         //create new variable
402         sciErr = createMatrixOfUnsignedInteger16(pvApiCtx, nbInputArgument(pvApiCtx) + 4, iRowsu16, iColsu16, pusDataOut);
403         if(sciErr.iErr)
404         {
405                 printError(&sciErr, 0);
406                 return 0;
407         }
408
409         //create new variable
410         sciErr = createMatrixOfInteger32(pvApiCtx, nbInputArgument(pvApiCtx) + 5, iRows32, iCols32, piDataOut);
411         if(sciErr.iErr)
412         {
413                 printError(&sciErr, 0);
414                 return 0;
415         }
416
417         //create new variable
418         sciErr = createMatrixOfUnsignedInteger32(pvApiCtx, nbInputArgument(pvApiCtx) + 6, iRowsu32, iColsu32, puiDataOut);
419         if(sciErr.iErr)
420         {
421                 printError(&sciErr, 0);
422                 return 0;
423         }
424
425         //assign allocated variables to Lhs position
426         AssignOutputVariable(pvApiCtx, 1) = nbInputArgument(pvApiCtx) + 1;
427         AssignOutputVariable(pvApiCtx, 2) = nbInputArgument(pvApiCtx) + 2;
428         AssignOutputVariable(pvApiCtx, 3) = nbInputArgument(pvApiCtx) + 3;
429         AssignOutputVariable(pvApiCtx, 4) = nbInputArgument(pvApiCtx) + 4;
430         AssignOutputVariable(pvApiCtx, 5) = nbInputArgument(pvApiCtx) + 5;
431         AssignOutputVariable(pvApiCtx, 6) = nbInputArgument(pvApiCtx) + 6;
432         return 0;
433 }
434
435 void* create_output(int _iCoeff, int _iSize, int _iRows, int _iCols, void* _pvDataIn)
436 {
437         int i = 0;
438         void* pvDataOut = (void*)malloc(_iSize * _iRows * _iCols);
439         for(i = 0 ; i < _iRows * _iCols ; i++)
440         {
441                 int iVal = 0;
442                 memcpy(&iVal, (char*)_pvDataIn + i * _iSize, _iSize);
443                 iVal *= _iCoeff;
444                 memcpy((char*)pvDataOut + i * _iSize, &iVal, _iSize);
445         }
446         return pvDataOut;
447 }
448 ]]></programlisting>
449     </refsection>
450     <refsection>
451         <title>Scilab test script</title>
452         <programlisting role="code_scilab"><![CDATA[ 
453 a8  = int8([    1   -2  3   -4  5; ..
454                 -6  7   -8  9   -10; ..
455                 11  -12 13  -14 15]);
456
457 au8 = uint8([   1   2   3   4   5; ..
458                 6   7   8   9   10; ..
459                 11  12  13  14  15]);
460
461 a16  = int16([  1   -2  3   -4  5; ..
462                 -6  7   -8  9   -10; ..
463                 11  -12 13  -14 15]);
464
465 au16 = uint16([ 1   2   3   4   5; ..
466                 6   7   8   9   10; ..
467                 11  12  13  14  15]);
468
469 a32 = int32([   1   -2  3   -4  5; ..
470                 -6  7   -8  9   -10; ..
471                 11  -12 13  -14 15]);
472
473 au32 = uint32([ 1   2   3   4   5; ..
474                 6   7   8   9   10; ..
475                 11  12  13  14  15]);
476
477 [c8, cu8, c16, cu16, c32, cu32] = read_integer(a8, au8, a16, au16, a32, au32);
478
479 if or(c8 <> a8 * 2) then error("failed"), end
480 if or(cu8 <> au8 * 4) then error("failed"), end
481 if or(c16 <> a16 * 8) then error("failed"), end
482 if or(cu16 <> au16 * 16) then error("failed"), end
483 if or(c32 <> a32 * 32) then error("failed"), end
484 if or(cu32 <> au32 * 64) then error("failed"), end
485  ]]></programlisting>
486     </refsection>
487 </refentry>