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 pSurfgiven the pUVParametercoordinates.

Reading the Result

If the function successfully evaluates pUVParameteron pSurf, the memory at pPointAndDerivativesis filled with a row-major 2D array representing the derivatives in the order of uand 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 (uand v) | == 2
  • 1 | 2 | U2 | Second derivative with respect to u | == 2

To retrieve the value in the table given the partial derivative orders uand vuse:pPointAndDerivatives[u * (uiNbDerivatives+1) + v]

When uiNbDerivativesis 0, the table contains a single element:

**** | ** 0**

  • 0 | Point

When uiNbDerivativesis 1, the array has 2 rows and 2 columns:

**** | ** 0** | ** 1**

  • 0 | Point | V
  • 1 | U |

When uiNbDerivativesis 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 pPointAndDerivativesdepends on the value of uiNbDerivatives:

The memory layout for pPointAndDerivativesis 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 pPointAndDerivativesmust reference an already initializedarray 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, pPointAndDerivativesmust 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_SUCCESSon success, or an error code on failure