API help 1
antoine ELIAS [Tue, 7 Jul 2009 13:45:46 +0000 (15:45 +0200)]
scilab/modules/core/help/en_US/api/CHAPTER [new file with mode: 0644]
scilab/modules/core/help/en_US/api/double_writing_api.xml [new file with mode: 0644]

diff --git a/scilab/modules/core/help/en_US/api/CHAPTER b/scilab/modules/core/help/en_US/api/CHAPTER
new file mode 100644 (file)
index 0000000..42e18dc
--- /dev/null
@@ -0,0 +1 @@
+title = Scilab Gateway API
diff --git a/scilab/modules/core/help/en_US/api/double_writing_api.xml b/scilab/modules/core/help/en_US/api/double_writing_api.xml
new file mode 100644 (file)
index 0000000..1cd42ea
--- /dev/null
@@ -0,0 +1,254 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2009  - DIGITEO - Antoine ELIAS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<refentry version="5.0-subset Scilab" xml:id="Double management writing_API"
+          xml:lang="en" 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">
+
+    <refnamediv>
+        <refname>Double writing</refname>
+
+        <refpurpose>
+            How to write matrices of doubles in a gateway.
+        </refpurpose>
+    </refnamediv>
+    <refsection>
+        <title>Description</title>
+        <para>This help describes how matrix of doubles can be handled through the Scilab API.</para>
+        <para>There are 2 types of functions which can be used to write in the memory of Scilab.</para>
+    </refsection>
+    <refsection>
+        <title>Create from existing data</title>
+        <synopsis>int createMatrixOfDouble(int _iVar, int _iRows, int _iCols, double* _pdblReal)</synopsis>
+        <synopsis>int createComplexMatrixOfDouble(int _iVar, int _iRows, int _iCols, double* _pdblReal, double* _pdblImg)</synopsis>
+    </refsection>
+    <refsection>
+        <title>Parameters</title>
+
+        <variablelist>
+            <varlistentry>
+                <term>_iVar</term>
+                <listitem>
+                    <para>
+                        Position in the Scilab memory where you want to put the variable
+                    </para>
+                </listitem>
+            </varlistentry>
+
+            <varlistentry>
+                <term>_iRows</term>
+                <listitem>
+                    <para>
+                        Number of rows of the new variable
+                    </para>
+                </listitem>
+            </varlistentry>
+
+            <varlistentry>
+                <term>_iCols</term>
+                <listitem>
+                    <para>
+                        Numbers of columns of the new variable
+                    </para>
+                </listitem>
+            </varlistentry>
+
+            <varlistentry>
+                <term>_pdblReal</term>
+                <listitem>
+                    <para>
+                        Address of real data array (size: _iCols * _iRows)
+                    </para>
+                </listitem>
+            </varlistentry>
+
+            <varlistentry>
+                <term>_pdblImg</term>
+                <listitem>
+                    <para>
+                        Address of imaginary data array (size: _iCols * _iRows)
+                    </para>
+                </listitem>
+            </varlistentry>
+
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Write directly in Scilab memory</title>
+        <synopsis>int allocMatrixOfDouble(int _iVar, int _iRows, int _iCols, double** _pdblReal)</synopsis>
+        <synopsis>int allocComplexMatrixOfDouble(int _iVar, int _iRows, int _iCols, double** _pdblReal, double** _pdblImg)</synopsis>
+    </refsection>
+    <refsection>
+        <title>Parameters</title>
+
+        <variablelist>
+            <varlistentry>
+                <term>_iVar</term>
+                <listitem>
+                    <para>
+                        Position in the Scilab memory where you want to put the variable
+                    </para>
+                </listitem>
+            </varlistentry>
+
+            <varlistentry>
+                <term>_iRows</term>
+                <listitem>
+                    <para>
+                        Number of rows of the new variable
+                    </para>
+                </listitem>
+            </varlistentry>
+
+            <varlistentry>
+                <term>_iCols</term>
+                <listitem>
+                    <para>
+                        Numbers of columns of the new variable
+                    </para>
+                </listitem>
+            </varlistentry>
+
+            <varlistentry>
+                <term>_pdblReal</term>
+                <listitem>
+                    <para>
+                        Returns address of real data array (size: _iCols * _iRows)
+                    </para>
+                </listitem>
+            </varlistentry>
+
+            <varlistentry>
+                <term>_pdblImg</term>
+                <listitem>
+                    <para>
+                        Returns address of imaginary data array (size: _iCols * _iRows)
+                    </para>
+                </listitem>
+            </varlistentry>
+
+        </variablelist>
+    </refsection>
+
+    <refsection>
+        <!--File_gateway: SCI/modules/core/tests/unit_tests/double_writing_api.c-->
+        <!--File_scilab: SCI/modules/core/tests/unit_tests/double_writing_api.tst-->
+        <!--Lib_name: double_writing-->
+        <!--Func_list: write_double-->
+        <title>Gateway Source</title>
+        <programlisting role="code gateway">
+            <![CDATA[
+int write_double(char *fname,unsigned long fname_len)
+{
+    int i,j;
+
+    //first variable info : real matrix of double 3 x 4
+    int iRows1          = 3;
+    int iCols1          = 4;
+    double* pdblReal1   = NULL;
+
+    //second variable info : complex matrix of double 4 x 6
+    int iRows2          = 4;
+    int iCols2          = 6;
+    double* pdblReal2   = NULL;
+    double* pdblImg2    = NULL;
+
+    /************************
+    *    First variable    *
+    ************************/
+    //alloc array of data in OS memory
+    pdblReal1 = (double*)malloc(sizeof(double) * iRows1 * iCols1);
+
+    //fill array with incremental values
+    //[ 0   1   2   3
+    //  4   5   6   7
+    //  8   9   10  11]
+    for(i = 0 ; i < iRows1 ; i++)
+    {
+        for(j = 0 ; j < iCols1 ; j++)
+        {
+            pdblReal1[i + iRows1 * j] = i * iCols1 + j;
+        }
+    }
+    //can be written in a single loop
+    //for(i = 0 ; i < iRows1 * iCols1; i++)
+    //{
+    //  pdblReal1[i] = i;
+    //}
+
+    //create a variable from a existing data array
+    createMatrixOfDouble(Rhs + 1, iRows1, iCols1, pdblReal1);
+
+    //after creation, we can free memory.
+    free(pdblReal1);
+    /*************************
+    *    Second variable    *
+    *************************/
+
+    //reserve space in scilab memory and fill it
+    allocComplexMatrixOfDouble(Rhs + 2, iRows2, iCols2, &pdblReal2, &pdblImg2);
+
+    //fill array with incremental values for real part and decremental for imaginary part
+    //[ 23i     1+22i       2+21i       3+20i       4+19i       5+18i
+    //  6+17i   7+16i       8+15i       9+14i       10+13i      11+12i
+    //  12+11i  13+10i      14+9i       15+8i       16+7i       17+6i
+    //  18+5i   19+4i       20+3i       21+2i       22+1i       23  ]
+    for(i = 0 ; i < iRows2 ; i++)
+    {
+       for(j = 0 ; j < iCols2 ; j++)
+        {
+            pdblReal2[i + iRows2 * j] = i * iCols2 + j;
+            pdblImg2 [i + iRows2 * j]  = (iRows2 * iCols2 - 1) - (i * iCols2 + j);
+        }
+    }
+    //can be written in a single loop
+    //for(i = 0 ; i < iRows2 * iCols2; i++)
+    //{
+    //  pdblReal2[i] = i;
+    //  pdblImg2 [i] = (iRows2 * iCols2 - 1) - i;
+    //}
+
+    // /!\ DO NOT FREE MEMORY, in this case, it's the Scilab memory
+
+
+    //assign allocated variables to Lhs position
+    LhsVar(1) = Rhs + 1;
+    LhsVar(2) = Rhs + 2;
+    PutLhsVar();
+    return 0;
+}
+        ]]>
+        </programlisting>
+    </refsection>
+
+    <refsection>
+        <title>Scilab test script</title>
+        <programlisting role="code_scilab">
+            <![CDATA[
+a_ref = [   0 1 2 3; ..
+            4 5 6 7; ..
+            8 9 10 11];
+b_ref = [   23*%i,      1+22*%i,    2+21*%i,    3+20*%i,    4+19*%i,    5+18*%i; ..
+            6+17*%i,    7+16*%i,    8+15*%i,    9+14*%i,     10+13*%i,  11+12*%i; ..
+            12+11*%i,   13+10*%i,   14+9*%i,    15+8*%i,    16+7*%i,    17+6*%i; ..
+            18+5*%i,    19+4*%i,    20+3*%i,    21+2*%i,    22+1*%i,    23];
+[a,b] = write_double();
+if or(a <> a_ref) then error("failed");end
+if or(b <>; b_ref) then error("failed");end
+            ]]>
+        </programlisting>
+    </refsection>
+</refentry>
\ No newline at end of file