
###############
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
   
   




