A3DSurfEvaluate

A3DStatus A3DSurfEvaluate(const A3DSurfBase *pSurf, const A3DVector2dData *pUVParameter, A3DUns32 uiNbDerivatives, A3DVector3dData *pPointAndDerivatives)
A3DStatus A3DSurfEvaluate(const A3DSurfBase* pSurf, const A3DVector2dData* pUVParameter, A3DUns32 uiNbDerivatives, 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 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)).

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