
###############
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.
   
   
   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*   \|  \| 
   
   
   
   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.
   
   
   
   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
   
   




