
###############
A3DSurfEvaluate
###############

.. c:function:: A3DStatus A3DSurfEvaluate(const A3DSurfBase *pSurf, const A3DVector2dData *pUVParameter, A3DUns32 uiNbDerivatives, A3DVector3dData *pPointAndDerivatives)

   .. rst-class:: sig-pretty-signature
   
      | :c:enum:`~A3DStatus` A3DSurfEvaluate(*const* :c:type:`~A3DSurfBase`\ \* **pSurf**\ , *const* :c:struct:`~A3DVector2dData`\ \* **pUVParameter**\ , :c:type:`~A3DUns32` **uiNbDerivatives**\ , :c:struct:`~A3DVector3dData`\ \* **pPointAndDerivatives**\ )
   
   Evaluate a point and its derivative on a surface.
   
   This function evaluates the point and its derivatives (1st and 2nd) on the surface ``pSurf`` given the ``pUVParameter`` coordinates.
   
   
      4.0
   
   
   **Return Values**
   
   
      **A3D_SUCCESS**\ :
   
   
      - ``uiNbDerivatives`` > *2*
      - \ ``pSurf`` is *0*
      - \ ``pUVParameter`` is *0*
      - \ ``pPointAndDerivatives`` is *0*
      - \ evaluation is not possible.
   
      **A3D_ERROR**\ : in the following cases:
   
   
   .. rubric:: Reading the Result
   
   
   If the function successfully evaluates ``pUVParameter`` on ``pSurf``\ , the memory at ``pPointAndDerivatives`` is filled with a row-major 2D array representing the derivatives in the order of *u* and *v*\ .
   
   **u**  \| **v**  \| **Content**  \| **Description**  \| **uiNbDerivatives** 
   
   
   - 0  \| 0  \| *Point*  \| The evaluated point at ``pUVParameter``  \|
   - 0  \| 1  \| *V*  \| First derivative with respect to *v*  \| ``>= 1``
   - 0  \| 2  \| *V2*  \| Second derivative with respect to *v*  \| ``== 2``
   - 1  \| 0  \| *U*  \| First derivative with respect to *u*  \| ``>= 1``
   - 1  \| 1  \| *UV*  \| Mixed first derivates (*u* and *v*\ )  \| ``== 2``
   - 1  \| 2  \| *U2*  \| Second derivative with respect to *u*  \| ``== 2``
   
   To retrieve the value in the table given the partial derivative orders ``u`` and ``v`` use: ``pPointAndDerivatives[u * (uiNbDerivatives+1) + v]``
   
   When ``uiNbDerivatives`` is *0*\ , the table contains a single element:
   
    \| **0** 
   
   
   - *0*  \| *Point*
   
   When ``uiNbDerivatives`` is *1*\ , the array has 2 rows and 2 columns:
   
    \| **0**  \| **1** 
   
   
   - *0*  \| *Point*  \| *V*
   - *1*  \| *U*  \|
   
   When ``uiNbDerivatives`` is *2*\ , the table has 3 rows and 3 columns:
   
    \| **0**  \| **1**  \| **2** 
   
   
   - *0*  \| *Point*  \| *V*  \| *V2*
   - *1*  \| *U*  \| *UV*  \|
   - *2*  \| *U2*  \|  \|
   
   .. rubric:: Memory Layout
   
   
   As a 2D array expressed in a C-style array, the memory layout for ``pPointAndDerivatives`` depends on the value of ``uiNbDerivatives``\ :
   
   The memory layout for ``pPointAndDerivatives`` is as follows:
   
   **uiNbDerivatives**  \| **0**  \| **1**  \| **2**  \| **3**  \| **4**  \| **5**  \| **6**  \| **7**  \| **8** 
   
   
   - *0*  \| *Point*  \|  \|  \|  \|  \|  \|  \|  \|
   - *1*  \| *Point*  \| *V*  \| *U*  \|  \|  \|  \|  \|  \|
   - *2*  \| *Point*  \| *V*  \| *V2*  \| *U*  \| *UV*  \|  \| *U2*  \|  \|
   
   The values left blank in this table correspond to uninitialized data. Dereferencing them is unsupported behavior.
   
   .. rubric:: Memory Management
   
   
   The pointer ``pPointAndDerivatives`` must reference an **already initialized** array of :c:struct:`~A3DVector3dData`\ . The allocated memory should be sufficient to store all results, and the required size depends on the value of ``uiNbDerivatives``\ :
   
   
   - ``uiNbDerivates`` = *0*\ : 1 element. 
   - ``uiNbDerivates`` = *1*\ : 4 elements. 
   - ``uiNbDerivates`` = *2*\ : 9 elements.
   
   In general, ``pPointAndDerivatives`` must point to an allocated memory of ``sizeof(A3DVector3dData * (uiNbDerivates + 1) * (uiNbDerivates + 1))``\ .
   
   :c:func:`~A3DSurfEvaluate` does not perform bound checking. Therefore, it is the caller's responsibility to ensure that the allocated memory is sufficient.
   
   **Parameters**
   
   
      **pSurf**\ : The surface on which the point will be evaluated.
   
      **pUVParameter**\ : The coordinates of the point to evaluate, expressed in UV parameeters on ``pSurf``\ .
   
      **uiNbDerivatives**\ : The number of derivatives to evaluate. This value cannot exceed *2*\ .
   
      **pPointAndDerivatives**\ : The resulting evaluation, stored in this pointer.
   
   
   **Returns**
   
   
      ``A3D_SUCCESS`` on success, or an error code on failure
   
   




