# HM_ExtAPI::CreateGeomFaceTrimmed()

Creates trimmed face in the HyperMesh database.

## Syntax

```
bool CreateGeomFaceTrimmed(
HM_EntityGeomFace& new_face,
const HM_EntityGeometrySurface& base_surf,
int number_of_loops,
const int* loop_coedge_counts,
const HM_EntityGeometryCurve* loop_coedge_curves,
const double* curve_start_params,
const double* curve_end_params,
const bool* coedge_curve_dirs,
int option_flags,
HM_EntityComponent comp
);
```

## Type

HyperMesh Ext API Function

## Description

Created face must have at least one loop that defines its external boundary in parametric space.

If the function succeeds, the return value is `true`. If the
function fails, the return value is `false`. To get extended
value information, call HM_ExtAPI::GetLastErrorCode().

Loop direction is defined in such a way that the loop is counterclockwise with respect to an outward pointing face normal. In other words, in a view where the face normal is directed towards the observer, the loop would have the face area on the left side.

In parametric space, the direction of the loops depends on geometric normal use defined by
the flag HM_ExtAPI::CF_SURF_REV in the parameter `option_flags`. If the
flag is not set, then the face normal is oriented in the same direction as the geometric
surface normal and the "face on the left" rule applies in parametric space as well. The
external loop of the face is oriented counterclockwise while all internal loops are oriented
clockwise.

If the HM_ExtAPI::CF_SURF_REV flag is set, then the face normal is reversed with respect to the geometric surface normal and all loops have the face on their right in parametric space. In this case, the external loop of the face is oriented clockwise while all internal loops are oriented counterclockwise.

Direction of the geometric normal of the surface is defined by the surface parameterization function S(U, V) as the direction of the cross-product of parametric derivatives:

N = ∂S(U, V)/∂U X ∂S(U, V)/∂V

The parameter `loop_coedge_curves` points to the array of curve handles
corresponding to curves used to construct loop coedges. Each curve is interpreted either as
parametric curve, or, if the flag HM_ExtAPI::CF_EDGES_3D is set in the
`option_flags` parameter, as a 3D curve that is assumed to be reasonably
close to the surface geometry. If 2D parametric curves are used, then the x and y
coordinates of each curve point is used as, respectively, U and V coordinates in the
parametric surface space. The z coordinate of the curve points is ignored.

The array contains curves for all loops. The order of the curves for each loop is defined by the direction of the loop. The curves for the coedges of the external loop must appear first in the array.

If direction of the loop is not defined, then the flag HM_ExtAPI::CF_CHECK_LOOP_DIR should
be set in the `option_flags` parameter to make sure consistent loop
orientation is determined internally.

Both `curve_start_params` and `curve_end_params` must be
NULL or not NULL at the same time. If both parameters are NULL, then the default parametric
range of each curve is used to create the coedge. Use the function
HM_ExtAPI::GeomCurveGetParameterBounds to obtain the curve parametric
range.

Curve directions in the loop can be defined by using the
`coedge_curve_dirs` parameter. If this parameter is NULL, then all curves
are assumed to be oriented in the loop direction. If the curve's orientation is not known,
then the flag HM_ExtAPI::CF_CHECK_EDGE_DIR should be set to make sure that the correct curve
orientation is determined internally.

Requires including hm_extapi.h.

## Inputs

`new_face`- [out] - Handle to a new face object.
`base_surf`- [in] - Handle to surface objects that was returned by previous calls to API functions. This parameter can also be NULL, in which case the function attempts to calculate the surface that fits the geometry of the input loop curves.
`number_of_loops`- [in] - Number of face loops.
`loop_coedge_counts`- [in] - Pointer to the array that contains the number of coedges in each loop. The number of entries in the array must equal the number_of_loops.
`loop_coedge_curves`- [in] - Pointer to the array of the curve handles returned by previous calls to API
functions. Each handle represents the curve geometry for each of the corresponding
coedges defining face loops. The number of entries in the array must be equal to the sum
of the loop coedge counts given by the array
`loop_coedge_counts`. The curves are defined in either 2D parametric space of the surface`base_surf`or, if the flag HM_ExtAPI::CF_EDGES_3D is set in`option_flags`, in 3D space. `curve_start_params`- [in] - If not NULL, then points to the array of values that define the lower
parametric bound of the corresponding curve from the array
`loop_coedge_curves`used to create the coedge. The number of entries in the array must equal the number of entries in the array`loop_coedge_curves`. `curve_end_params`- [in] - If not NULL, then points to the array of values that define the upper
parametric bound of the corresponding curve from the array
`loop_coedge_curves`used to create the coedge. The number of entries in the array must equal the number of entries in the array`loop_coedge_curves`. `coedge_curve_dirs`- [in] - If not NULL, then points to the array of flags that define the direction of the
curves given by
`loop_coedge_curves`with respect to the loop direction. The value of`true`indicates that the direction of the curve within the coedge is the same as the loop direction. The value of`false`indicates that the direction of the curve is opposite to the direction of the loop. If the parameter is NULL, then the value of`true`is assumed for all curves. `option_flags`- [in] – bitwise combination of additional option flags. The following flags are defined in the hm_extapi.h header file:
`comp`- [in] - If not NULL, then the component where the face is created. If NULL, then the line is created in the current component.

## Errors

If some inconsistencies are found in the input parameters or geometries, the function may
fail and return `false`.