IXpsOMGeometryFigure：：SetSegments 方法 (xpsobjectmodel.h)

项目
03/09/2024

设置图中段的段信息和数据点。

语法

HRESULT SetSegments(
  [in] UINT32                 segmentCount,
  [in] UINT32                 segmentDataCount,
  [in] const XPS_SEGMENT_TYPE *segmentTypes,
  [in] const FLOAT            *segmentData,
  [in] const BOOL             *segmentStrokes
);

参数

[in] segmentCount

段数。

此值也是 由 segmentTypes 和 segmentStrokes 引用的数组中的元素数。

[in] segmentDataCount

段数据点的数目。

此值也是 由 segmentData 引用的数组中的元素数。

[in] segmentTypes

XPS_SEGMENT_TYPE变量的数组。 segmentCount 的值指定此数组中的元素数。

[in] segmentData

段数据值的数组。 segmentDataCount 的值指定此数组中的元素数。

[in] segmentStrokes

段笔划值的数组。 segmentCount 的值指定此数组中的元素数。

返回值

该方法返回 HRESULT。可能的值包括但不限于下表中的值。有关此表中未列出的 XPS 文档 API 返回值的信息，请参阅 XPS 文档错误。

返回代码	说明
S_OK	方法成功。
E_INVALIDARG	segmentTypes 包含无法识别类型的值。或者， segmentData 数组中的条目数大于 segmentTypes 数组中的条目数。
E_POINTER	segmentTypes、 segmentData 或 segmentStrokes 为 NULL。
XPS_E_INVALID_FLOAT	segmentData 包含一个 FLOAT 值，该值是无限的或不是 NAN) (数字。
XPS_E_MISSING_SEGMENT_DATA	在 segmentData 中传递的数组的条目数少于在 segmentTypes 中传递的数组。
XPS_E_NEGATIVE_FLOAT	在 segmentData 中传递的数组中的条目包含负值，但它必须包含非负值。

注解

几何线段由起点、段类型以及值由段类型确定的其他参数描述。第一段起点的坐标是 geometry 图形的一个属性，通过调用 SetStartPoint 设置。每个后续段的起点是上一段的终点。

定义线段的数据值的数量取决于线段类型。下表描述了必须用于每个段类型的特定所需数据值集。在 segmentData 参数中传递的段数据数组中的值必须与在 segmentTypes 参数中传递的数组中的XPS_SEGMENT_TYPE值相对应。例如，如果第一条线段的线段类型值为 XPS_SEGMENT_TYPE_LINE，则 segmentData 数组中的前两个数据值将是该线段终点的 x 和 y 坐标;如果下一段的段类型值为 XPS_SEGMENT_TYPE_BEZIER，则 segmentData 数组中的接下来六个值将描述该段的特征;几何图形中的每个线段等。

段类型	所需数据值
XPS_SEGMENT_TYPE_LINE	两个数据值：线段线终点的 x 坐标。段线终点的 y 坐标。
XPS_SEGMENT_TYPE_ARC_LARGE_CLOCKWISE	五个数据值：弧的终点的 x 坐标。弧线终点的 y 坐标。沿 x 轴的椭圆半径的长度。椭圆沿 y 轴半径的长度。旋转角度。
XPS_SEGMENT_TYPE_ARC_SMALL_CLOCKWISE	五个数据值：弧的终点的 x 坐标。弧线终点的 y 坐标。沿 x 轴的椭圆半径的长度。椭圆沿 y 轴半径的长度。旋转角度。
XPS_SEGMENT_TYPE_ARC_LARGE_COUNTERCLOCKWISE	五个数据值：弧的终点的 x 坐标。弧线终点的 y 坐标。沿 x 轴的椭圆半径的长度。椭圆沿 y 轴半径的长度。旋转角度。
XPS_SEGMENT_TYPE_ARC_SMALL_COUNTERCLOCKWISE	五个数据值：弧的终点的 x 坐标。弧线终点的 y 坐标。沿 x 轴的椭圆半径的长度。椭圆沿 y 轴半径的长度。旋转角度。
XPS_SEGMENT_TYPE_BEZIER	六个数据值：贝塞尔曲线第一个控制点的 x 坐标。贝塞尔曲线第一个控制点的 y 坐标。贝塞尔曲线第二个控制点的 x 坐标。贝塞尔曲线第二个控制点的 y 坐标。贝塞尔曲线终点的 x 坐标。贝塞尔曲线终点的 y 坐标。
XPS_SEGMENT_TYPE_QUADRATIC_BEZIER	四个数据值：四边形贝塞尔曲线控制点的 x 坐标。四边形贝塞尔曲线控制点的 y 坐标。四边形贝塞尔曲线终点的 x 坐标。四边形贝塞尔曲线终点的 y 坐标。

若要获取图中的段类型，请调用 GetSegmentTypes。

以下代码示例演示了创建和填充 SetSegments 所需的缓冲区的一种方法。

在第一个代码示例中， AddSegmentDataToArrays 方法获取描述单个段的数据点，并将其存储在 SetSegments 方法所需的三个不同的数据缓冲区中。作为参数传递给 AddSegmentDataToArrays 的数据缓冲区由调用方法管理，如 AddSegmentDataToArrays 后面的代码示例所示。

HRESULT
AddSegmentDataToArrays(
    XPS_SEGMENT_TYPE        segmentType,
    BOOL                    segmentStroke,
    FLOAT                   *segmentPoints,
    UINT32                  *segmentsAvailable,
    UINT32                  *segmentPointsAvailable,
    XPS_SEGMENT_TYPE        **segmentTypeBuffer,
    BOOL                    **segmentStrokeBuffer,
    FLOAT                   **segmentPointBuffer
)
/*
Description:

Populates the buffers required by IXpsOMGeometryFigure::SetSegmentData
using data and buffers provided by the calling method.

Parameters:

segmentType
    IN: XPS_SEGMENT_TYPE value that specifies the segment type for
        the current segment.

segmentStroke
    IN: BOOL value that specifies whether the current segment 
        is stroked.

*segmentPoints
    IN: pointer to an array of FLOAT values that specify the 
        segment's data points. The number of values in the array
        depend on the value of the segmentType parameter.

*segmentsAvailable
    IN: the number of values that remain unused in the
        segmentTypeBuffer and the segmentStrokeBuffer.
        This value must be >= 1 when calling the method.
    OUT:  the number of values that remain unused in the
        segmentTypeBuffer and the segmentStrokeBuffer after
        segmentType and segmentStroke have been added. If the 
        method was successful, the returned value is one less 
        than the value passed in to the method.

*segmentPointsAvailable
    IN: the number of values that remain unused in the
        segmentPointBuffer.    This value must be greater-than or equal
        to the number of points required by the segmentType value.
    OUT:  the number of values that remain unused in the
        segmentPointBuffer after the segmentPoints have been added.
        The returned value depends on the segmentType value.

**segmentTypeBuffer
    IN: the first free element in the buffer that receives the segment
        type values.
    OUT: the first free element in the buffer that receives the segment
        type values. If the method is successful, this will be the element
        after the element pointed to by this value before the method 
        was called.

**segmentStrokeBuffer
    IN: the first free element in the buffer that receives the segment
        stroke values.
    OUT: the first free element in the buffer that receives the segment
        stroke values. If the method is successful, this will be the element
        after the element pointed to by this value before the method 
        was called.

**segmentPointBuffer
    IN: the first free element in the buffer that receives the segment
        point values.
    OUT: the first free element in the buffer that receives the segment
        point values. If the method is successful, the element referenced
        by this value will depend on the segment type.

Remarks.
1) the buffers and values passed into this method are managed by
    the calling method.

2) if the value returned in segmentsAvailable is 0, segmentTypeBuffer
    and segmentStrokeBuffer point to invalid memory.

3) if the value returned in segmentPointsAvailable is 0, segmentPointBuffer
    point to invalid memory.

*/
{
    HRESULT hr = S_OK;

    // test to see if there is sufficient space in the 
    // segmentTypeBuffer and the segmentStrokeBuffer before
    // proceeding
    if (*segmentsAvailable == 0)
    {
        hr = HRESULT_FROM_WIN32(ERROR_MORE_DATA);
    }

    if (SUCCEEDED(hr))
    {
        // process the data based on the segment type
        switch (segmentType) 
        {
            case    XPS_SEGMENT_TYPE_ARC_LARGE_CLOCKWISE:
            case    XPS_SEGMENT_TYPE_ARC_LARGE_COUNTERCLOCKWISE:
            case    XPS_SEGMENT_TYPE_ARC_SMALL_CLOCKWISE:
            case    XPS_SEGMENT_TYPE_ARC_SMALL_COUNTERCLOCKWISE:
                if (*segmentPointsAvailable >= 5) 
                {
                    // 5 data points
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<arc end point (x)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<arc end point (y)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<arc radius (x)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<arc radius (y)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<arc angle
                    *segmentPointsAvailable -= 5;
                }
                else
                {
                    hr = HRESULT_FROM_WIN32(ERROR_MORE_DATA);
                }
                break;
            case    XPS_SEGMENT_TYPE_BEZIER:
                if (*segmentPointsAvailable >= 6) 
                {
                    // 6 data points
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<control point 1 (x)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<control point 1 (y)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<control point 2 (x)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<control point 2 (y)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<end point (x)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<end point (y)
                    *segmentPointsAvailable -= 6;
                }
                else
                {
                    hr = HRESULT_FROM_WIN32(ERROR_MORE_DATA);
                }
                break;
            case    XPS_SEGMENT_TYPE_LINE:
                if (*segmentPointsAvailable >= 2) 
                {
                    // 2 data points
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<end point (x)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<end point (y)
                    *segmentPointsAvailable -= 2;
                }
                else
                {
                    hr = HRESULT_FROM_WIN32(ERROR_MORE_DATA);
                }
                break;
            case    XPS_SEGMENT_TYPE_QUADRATIC_BEZIER:
                if (*segmentPointsAvailable >= 4) 
                {
                    // 4 data points
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<control point 2 (x)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<control point 2 (y)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<end point (x)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<end point (y)
                    *segmentPointsAvailable -= 4;
                }
                else
                {
                    hr = HRESULT_FROM_WIN32(ERROR_MORE_DATA);
                }
                break;
            default:
                // unrecognized segment type
                hr = E_UNEXPECTED;
                break;
        }

    }

    if (SUCCEEDED(hr))
    {
        // Copy segment type and segment stroke values
        // to array and decrement number of array values
        // that remain unused.
        //
        // The space available for these operations was
        // tested at the beginning of the method.
        *(*segmentTypeBuffer)++ = segmentType;
        *(*segmentStrokeBuffer)++ = segmentStroke;
        *segmentsAvailable--;
    } 

    return hr;
}

在此代码示例中， UpdateSegmentData 创建 SetSegments 方法所需的数据缓冲区，并调用上述代码示例中的 AddSegmentDataToArrays 方法，以使用段数据填充它们。填充缓冲区后，将调用 SetSegments 将此数据添加到几何图形。

注意实际段数据未显示在这些代码示例中。

HRESULT
UpdateSegmentData (
    IXpsOMGeometryFigure    *geometryFigure,
    UINT32                  segmentCount,
    UINT32                  segmentDataCount
)
/*
    Note that this method is not complete and only includes
    the code necessary to show how the SetSegments call is used.

    In this sample, the geometryFigure, segmentCount, and
    segmentDataCount values are assumed to have been initialized
    outside of this example.
*/
{
    HRESULT             hr = S_OK;
    XPS_SEGMENT_TYPE    segmentType = (XPS_SEGMENT_TYPE)0;
    BOOL                segmentStroke = FALSE;
    FLOAT               segmentPoints = 0;
    UINT32              segmentsAvailable = 0;
    UINT32              segmentPointsAvailable = 0;
    // these buffers are sized and allocated based on 
    //    the segment data to store.
    XPS_SEGMENT_TYPE    *segmentTypeBuffer = NULL;
    BOOL                *segmentStrokeBuffer = NULL;
    FLOAT               *segmentPointBuffer = NULL;

    XPS_SEGMENT_TYPE    *nextSegmentTypeValue = NULL;
    BOOL                *nextSegmentStrokeValue = NULL;
    FLOAT               *nextSegmentPointValue = NULL;

    // segment data is created outside of this example

    // allocate buffers as required using information 
    // from segment data. This can be dynamic or static
    // depending on how the segment information is managed.
    // This example assumes that the segment information 
    // does not change during this method.

    // initialize "next" pointers to point to the first
    // element in each array.
    nextSegmentTypeValue = segmentTypeBuffer;
    nextSegmentStrokeValue = segmentStrokeBuffer;
    nextSegmentPointValue = segmentPointBuffer;

    // for each segment in the figure, add the 
    // segment data to the buffers

        hr = AddSegmentDataToArrays(
                segmentType,
                segmentStroke,
                &segmentPoints,
                &segmentsAvailable,
                &segmentPointsAvailable,
                &nextSegmentTypeValue,
                &nextSegmentStrokeValue,
                &nextSegmentPointValue);
        
    if (SUCCEEDED(hr))
    {
        // set segment data
        hr = geometryFigure->SetSegments (
            segmentCount,
            segmentDataCount,
            segmentTypeBuffer,
            segmentPointBuffer,
            segmentStrokeBuffer);
    }
    // clean up buffers

    return hr;
}

要求

要求	值
最低受支持的客户端	Windows 7、带 SP2 的 Windows Vista 和适用于 Windows Vista 的平台更新 [桌面应用 \|UWP 应用]
最低受支持的服务器	Windows Server 2008 R2、Windows Server 2008 SP2 和适用于 Windows Server 2008 的平台更新 [桌面应用 \|UWP 应用]
目标平台	Windows
标头	xpsobjectmodel.h

另请参阅

通过

IXpsOMGeometryFigure：：SetSegments 方法 (xpsobjectmodel.h)

语法

参数

返回值

注解

要求

另请参阅

反馈

其他资源