Go to Google Code Home
Google SketchUp SkpReader C++ API Documentation (Labs)

Public Member Functions | Properties

ISkpFace Interface Reference

A Face interface. More...

Inheritance diagram for ISkpFace:
SkpFace

List of all members.

Public Member Functions

HRESULT CreateMesh ([in] unsigned long type,[in] ISkpCorrectPerspective *pPerspective,[out, retval] ISkpPolygonMesh **pVal)
 Tesselate the face and return an ISkpPolygonMesh.
HRESULT GetAttachedComponentInstances ([out, retval]ISkpComponentInstances **pVal)
 [propget] Get the ISkpComponentInstance objects that are attached to this face.
HRESULT GetUVHelper ([in]BOOL front,[in]BOOL back,[in] ISkpCorrectPerspective *pPerspective,[out, retval]ISkpUVHelper **pHelper)
 Creates a UV helper for the face.
HRESULT GetUVHelperWithTextureHandle ([in]BOOL front,[in]BOOL back,[in] ISkpCorrectPerspective *pPerspective,[in] long textureHandle,[out, retval]ISkpUVHelper **pHelper)
 Returns a UVHelper given a specific texture handle.
HRESULT CreateMeshWithUVHelper ([in] unsigned long type,[in] ISkpUVHelper *pUVHelper,[out, retval] ISkpPolygonMesh **pVal)
 Tesselates the face using the given UVHelper to populate the PolygonMesh with proper UV values.
HRESULT GetFrontPushPins ([out] unsigned short *length,[out] double pushpins[16],[out] double projection_vector[3])
 [propget] Returns the number of front face pushpins, the pushpins, and the projection. length will be a value between 0 and 4. pushpins is returned in the following order: u0, v0, x0, y0, u1, v1, x1, y1, u2, v2, x2, y2, u3, v3, x3, y3 where un, vn is the texture coordinate point, and xn, yn is the arbitrary axis point. A return value of 0, 0, 0 for the projection vector indicates the texture is projected on the normal vector of the face.
HRESULT GetBackPushPins ([out] unsigned short *length,[out] double pushpins[16],[out] double projection_vector[3])
 [propget] Returns the number of front face pushpins, the pushpins, and the projection. length will be a value between 0 and 4. pushpins is returned in the following order: u0, v0, x1, y1, u1, v1, x2, y2, u2, v2, x3, y3, u3, v3, x3, y3 where un, vn is the pushpin position, and xn, yn is the arbitrary axis point. A return value of 0, 0, 0 for the projection vector indicates the texture proejcted on the normal vector of the face.

Properties

ISkpEdgeUses EdgeUses [get]
 [propget] Get the EdgeUses that are used by this Face.
ISkpLoops Loops [get]
 [propget] Get the Loops that define this Face.
ISkpLoop OuterLoop [get]
 [propget] Get the outer loop defining the perimeter of this Face.
ISkpOpenings Openings [get]
 [propget] Get the ISkpOpening objects that cut this Face.
ISkpEdges Edges [get]
 [propget] Get the ISkpEdge objects that define the inner and outer loops of this face.
ISkpVertices Vertices [get]
 [propget] Get the ISkpVertex objects that deliminate the Edges that define the Face.
double Area [get]
 [propget] Compute the area of the face, taking into account all the inner loops and cuts from openings.
ISkpPlane Plane [get]
 [propget] Get the ISkpPlane object that represents the underlying geometry of the face.
ISkpMaterial BackMaterial [get]
 [propget] Get the ISkpMaterial used on the back of this face.
ISkpMaterial FrontMaterial [get]
 [propget] Get the ISkpMaterial used on the front of this face.

Detailed Description

A Face interface.

An ISkpFace is defined by an outer loop and a collection of inner loops. The outer loop is always traversed counter clockwise with respect to the normal of the face.

A loop is a connected collection of ISkpEdgeUse objects. An ISkpEdgeUse references an ISkpEdge along with a direction: is the ISkpEdgeUse using the ISkpEdge in the same direction as the Edge's "natural" orientation?

To better understand this, consider the following situation where one finds two polygons P1 and P2:

PolygonsWithEdges.PNG

The edges are oriented in such a way that P1's edges are traversed counterclockwise about its normal (assuming the normal extends out of the screen, as opposed to into the screen), whereas P2's edges are traversed clockwise.

In SketchUp, a face is defined by an outer loop which is traversed counterclockwise with respect to the face's normal. This loop object must somehow be defined in terms of the edges in the system, but clearly in this example there is a problem with using the edges directly for P2.

The SketchUp modeler addresses this problem by introducing edgeuses, which are little more than an object that encapsulates a reference to an edge along with a flag indicating whether the edgeuse should be traversed in the same direction as the edge, or reversed.

If we draw in the edge uses (denoted e#) then we might have:

PolygonsWithEdgeUses.PNG

The polygon denoted P1 is enclosed by the edges E1, E2, E3 and E4 via reference through edgeuses e1, e2, e3 and e4. These edgeuses do not reverse their orientation via their respective edges.

Openings are cuts in the face occuring because of a cut-component being attached to the face.

Examples:

CreateMesh.cpp, and EntityInfo.cpp.


Member Function Documentation

HRESULT ISkpFace::CreateMesh ( [in] unsigned long  type,
[in] ISkpCorrectPerspective pPerspective,
[out, retval] ISkpPolygonMesh **  pVal 
)

Tesselate the face and return an ISkpPolygonMesh.

The type parameter allows the caller to specify which points in the mesh should be computed: the x, y, z points, the front and back u, v, q points and the vertex normals.

Parameters:
type A combination of the SkpMeshType enumeration taken by combining values with a logical "or" (the '|' operator in C++).
pPerspective A corrected perspective object, typically obtained from the ISkpTextureWriter object.
Return values:
pVal The ISkpPolygonMesh
Returns:
S_OK : if successful
E_POINTER : if any of the inputs are NULL
E_FAIL : on internal errors.
Examples:
CreateMesh.cpp.
HRESULT ISkpFace::CreateMeshWithUVHelper ( [in] unsigned long  type,
[in] ISkpUVHelper pUVHelper,
[out, retval] ISkpPolygonMesh **  pVal 
)

Tesselates the face using the given UVHelper to populate the PolygonMesh with proper UV values.

The type parameter should be aligned with the parameters used when getting the UVHelper.

Parameters:
type A combination of the SkpMeshType enumeration taken by combining values with a logical "or" (the '|' operator in C++).
pUVHelper The UV helper for this face, set up with the same front/back parameters as given in the 'type' parameter here, and set to use the correct image.
Return values:
pVal The ISkpPolygonMesh
Returns:
S_OK : if successful
E_POINTER : if any of the inputs are NULL
E_FAIL : on internal errors.
See also:
GetUVHelperWithTextureHandle
HRESULT ISkpFace::GetAttachedComponentInstances ( [out, retval] ISkpComponentInstances **  pVal  ) 

[propget] Get the ISkpComponentInstance objects that are attached to this face.

The component instances of type "opening" that are attached to this face define the openings in the face.

See also:
ISkpComponentInstance::GetAttachedComponentInstances
Return values:
pVal The ISkpComponentInstance objects that are attached to this face.
Returns:
S_OK : if successful
E_POINTER : if any of the inputs are NULL
E_FAIL : on internal errors.
HRESULT ISkpFace::GetBackPushPins ( [out] unsigned short *  length,
[out] double  pushpins[16],
[out] double  projection_vector[3] 
)

[propget] Returns the number of front face pushpins, the pushpins, and the projection. length will be a value between 0 and 4. pushpins is returned in the following order: u0, v0, x1, y1, u1, v1, x2, y2, u2, v2, x3, y3, u3, v3, x3, y3 where un, vn is the pushpin position, and xn, yn is the arbitrary axis point. A return value of 0, 0, 0 for the projection vector indicates the texture proejcted on the normal vector of the face.

Return values:
length The number of pushpins
pushpins The pushpins
projection_vector The projection_vector
Returns:
S_OK : if successful
E_POINTER : if length, pushpins, or projection_vector is NULL.
E_FAIL: Internal errors.
HRESULT ISkpFace::GetFrontPushPins ( [out] unsigned short *  length,
[out] double  pushpins[16],
[out] double  projection_vector[3] 
)

[propget] Returns the number of front face pushpins, the pushpins, and the projection. length will be a value between 0 and 4. pushpins is returned in the following order: u0, v0, x0, y0, u1, v1, x1, y1, u2, v2, x2, y2, u3, v3, x3, y3 where un, vn is the texture coordinate point, and xn, yn is the arbitrary axis point. A return value of 0, 0, 0 for the projection vector indicates the texture is projected on the normal vector of the face.

Return values:
length The number of pushpins
pushpins The pushpins
projection_vector The projection_vector
Returns:
S_OK : if successful
E_POINTER : if length, pushpins, or projection_vector is NULL.
E_FAIL: Internal errors.
HRESULT ISkpFace::GetUVHelper ( [in] BOOL  front,
[in] BOOL  back,
[in] ISkpCorrectPerspective pPerspective,
[out, retval] ISkpUVHelper **  pHelper 
)

Creates a UV helper for the face.

Parameters:
front If TRUE, will compute the UV coordinates for the front of the face.
back If TRUE, will compute the UV coordinates for the back of the face.
pPerspective A required input that must be created via the ISkpTextureWriter with this face loaded.
Deprecated:
This method has been deprecated in favor of the GetUVHelperWithTextureHandle method.
Return values:
pHelper The resulting helper.
Returns:
S_OK : if successful
E_POINTER : if any of the inputs are NULL
E_FAIL : on internal errors.
HRESULT ISkpFace::GetUVHelperWithTextureHandle ( [in] BOOL  front,
[in] BOOL  back,
[in] ISkpCorrectPerspective pPerspective,
[in] long  textureHandle,
[out, retval] ISkpUVHelper **  pHelper 
)

Returns a UVHelper given a specific texture handle.

This method is typically used when the client application has determined that the face does not have a texture of its own, rather it should inherit its texture from an owning Component Instance. The handle passed in would be the handle of the texture applied to the owning component instance.

This method can, and probably should, be used in place of GetUVHelper(), since it will work correctly in the case where the textureHandle is the handle of this face, or in the case of the inherited materials.

Parameters:
front If TRUE, will compute the UV coordinates for the front of the face.
back If TRUE, will compute the UV coordinates for the back of the face.
pPerspective A required input that must be created via the ISkpTextureWriter with this face loaded.
textureHandle The handle of the image that should be mapped to the face.
Return values:
pHelper The resulting helper.
Returns:
  • S_OK : if successful
  • E_POINTER : if any of the inputs are NULL
  • E_FAIL : on internal errors.

Property Documentation

double ISkpFace::Area [get]

[propget] Compute the area of the face, taking into account all the inner loops and cuts from openings.

Return values:
pVal The area of the face.
Returns:
S_OK : if successful
E_POINTER : if any of the inputs are NULL
E_FAIL : on internal errors.
ISkpMaterial ISkpFace::BackMaterial [get]

[propget] Get the ISkpMaterial used on the back of this face.

Return values:
pVal The ISkpMaterial used on the back of the face.
Returns:
S_OK : if successful
S_FALSE : if the back face has no material - in which case the object's color defaults
E_POINTER : if any of the inputs are NULL
E_FAIL : on internal errors.
ISkpEdges ISkpFace::Edges [get]

[propget] Get the ISkpEdge objects that define the inner and outer loops of this face.

This ISkpEdge object can also be obtained by looking at the EdgeUses of this face, and then the corresponding Edges of the EdgeUses.

Return values:
pVal The non-NULL collection of ISkpEdge objects.
Returns:
S_OK : if successful
E_POINTER : if any of the inputs are NULL
E_FAIL : on internal errors.
ISkpEdgeUses ISkpFace::EdgeUses [get]

[propget] Get the EdgeUses that are used by this Face.

Return values:
pVal The non-NULL collection of ISkpEdgeUse objects.
Returns:
S_OK : if successful
E_POINTER : if any of the inputs are NULL
E_FAIL : on internal errors.
ISkpMaterial ISkpFace::FrontMaterial [get]

[propget] Get the ISkpMaterial used on the front of this face.

Return values:
pVal The ISkpMaterial used on the front of the face.
Returns:
S_OK : if successful
S_FALSE : if the front face has no material - in which case the object's color defaults
E_POINTER : if any of the inputs are NULL
E_FAIL : on internal errors.
ISkpLoops ISkpFace::Loops [get]

[propget] Get the Loops that define this Face.

This collection of loops includes both the outer loop (as the 0th in the collection) and all inner loops. It does not, however, include inner loops that are the result of placing a so-called "opening component" on the face.

Return values:
pVal The non-NULL collection of ISkpLoop objects.
Returns:
S_OK : if successful
E_POINTER : if any of the inputs are NULL
E_FAIL : on internal errors.
ISkpOpenings ISkpFace::Openings [get]

[propget] Get the ISkpOpening objects that cut this Face.

Return values:
pVal The non-NULL collection of ISkpOpening objects.
Returns:
S_OK : if successful
E_POINTER : if any of the inputs are NULL
E_FAIL : on internal errors.
ISkpLoop ISkpFace::OuterLoop [get]

[propget] Get the outer loop defining the perimeter of this Face.

Return values:
pVal The ISkpLoop object that is the outer loop of this Face.
Returns:
S_OK : if successful
E_POINTER : if any of the inputs are NULL
E_FAIL : on internal errors.
ISkpPlane ISkpFace::Plane [get]

[propget] Get the ISkpPlane object that represents the underlying geometry of the face.

Return values:
pVal The ISkpPlane upon which this face lives.
Returns:
S_OK : if successful
E_POINTER : if any of the inputs are NULL
E_FAIL : on internal errors.
ISkpVertices ISkpFace::Vertices [get]

[propget] Get the ISkpVertex objects that deliminate the Edges that define the Face.

Return values:
pVal The non-NULL collection of ISkpVertex objects.
Returns:
S_OK : if successful
E_POINTER : if any of the inputs are NULL
E_FAIL : on internal errors.

©2010 Google - Google Home - About Google