ScriptShapeOpenType 函数 (usp10.h)
使用 OpenType 信息为 Unicode 运行生成字形和可视属性。 每个运行都包含对此函数的一次调用。
语法
HRESULT ScriptShapeOpenType(
[in, optional] HDC hdc,
[in, out] SCRIPT_CACHE *psc,
[in, out] SCRIPT_ANALYSIS *psa,
[in] OPENTYPE_TAG tagScript,
[in] OPENTYPE_TAG tagLangSys,
[in, optional] int *rcRangeChars,
[in, optional] TEXTRANGE_PROPERTIES **rpRangeProperties,
[in] int cRanges,
[in] const WCHAR *pwcChars,
[in] int cChars,
[in] int cMaxGlyphs,
[out] WORD *pwLogClust,
[out] SCRIPT_CHARPROP *pCharProps,
[out] WORD *pwOutGlyphs,
[out] SCRIPT_GLYPHPROP *pOutGlyphProps,
[out] int *pcGlyphs
);
参数
[in, optional] hdc
设备上下文的句柄。 有关详细信息，请参阅 缓存。
[in, out] psc
指向标识脚本缓存 的SCRIPT_CACHE 结构的指针。
[in, out] psa
指向从先前调用 ScriptItemizeOpenType 获取的SCRIPT_ANALYSIS结构的指针。 结构标识整形引擎，以便可以正确形成字形。
或者，应用程序可以将此参数设置为 NULL 以接收未筛选的结果。
[in] tagScript
定义编写系统的 OpenType 脚本标记的 OPENTYPE_TAG 结构。
[in] tagLangSys
包含编写系统的 OpenType 语言标记 的OPENTYPE_TAG 结构。
[in, optional] rcRangeChars
每个 区域中的字符数组。 数组元素的数目由 cRanges 指示。 此数组元素的值加起来就是 cChars 的值。
[in, optional] rpRangeProperties
TEXTRANGE_PROPERTIES结构的数组，每个结构表示一个 OpenType 功能范围。 结构数由 cRanges 参数指示。 有关 rpRangeProperties 的详细信息，请参阅备注部分。
[in] cRanges
OpenType 功能范围的数量。
[in] pwcChars
指向包含运行的 Unicode 字符数组的指针。
[in] cChars
Unicode 运行中的字符数。
[in] cMaxGlyphs
要生成的最大字形数。
[out] pwLogClust
指向缓冲区的指针，此函数在其中检索逻辑 群集 信息数组。 每个数组元素对应于 Unicode 字符数组中的一个字符。 每个元素的值都是从运行中的第一个字形到包含相应字符的群集中第一个字形的偏移量。 请注意，当 SCRIPT_ANALYSIS 结构的 fRTL 成员为 TRUE 时，元素会随着数组的读取而减少。
[out] pCharProps
指向缓冲区的指针，此函数在其中检索由 cChars 指示的长度的字符属性值数组。
[out] pwOutGlyphs
指向缓冲区的指针，此函数在其中检索字形数组。
[out] pOutGlyphProps
指向缓冲区的指针，此函数在其中检索每个检索到的字形的属性数组。 值的长度等于 pcGlyphs 的值。 由于每个字形都指示一个字形属性，因此此参数的值指示 cMaxGlyphs 指定的元素数。
[out] pcGlyphs
指向此函数检索 pwOutGlyphs 中指示的字形数的位置的指针。
返回值
如果成功，则返回 0。 如果函数不成功，则返回非零 HRESULT 值。 在所有错误情况下，所有输出数组值的内容都是未定义的。
错误返回包括：
- E_OUTOFMEMORY。 cMaxGlyphs 指示的输出缓冲区长度不足。
- E_PENDING。 psc 参数指定的脚本缓存不包含足够的信息来调整字符串，并且设备上下文已作为 NULL 传递，因此函数无法完成整形过程。 应用程序应为运行设置正确的设备上下文，并使用 hdc 中的相应上下文值和所有其他参数相同再次调用此函数。
- USP_E_SCRIPT_NOT_IN_FONT。 与设备上下文对应的字体不支持所需的脚本。 应用程序应使用 ScriptGetCMap 或其他方法来选择其他字体。
注解
ScriptShapeOpenType 优先于较旧的 ScriptShape 函数。 ScriptShapeOpenType 的一些优点包括：
- 参数直接对应于字体布局表中的 OpenType 标记。
- 参数定义应用于每个字符的特征。
- 输入分为运行。 每个运行都有 OpenType 属性，并且包含对 ScriptShapeOpenType 的单个调用。
如果字体或操作系统不支持字形索引，则此函数可以设置SCRIPT_ANALYSIS结构的 fNoGlyphIndex 成员。
应用程序可以调用 ScriptShapeOpenType 来确定字体是否支持给定字符串中的字符。 如果函数返回S_OK，则应用程序应检查缺少字形的输出。 如果在SCRIPT_ANALYSIS结构中将 fLogicalOrder 设置为 TRUE，则函数始终按与原始 Unicode 字符相同的顺序生成字形。 如果 fLogicalOrder 设置为 FALSE，则函数将按相反顺序从右到左生成项，以便 ScriptTextOut 在调用 ExtTextOut 之前不必反转它们。
如果 SCRIPT_ANALYSIS 的 eScript 成员设置为 SCRIPT_UNDEFINED，则禁用整形。 在本例中， ScriptShapeOpenType 显示字体 cmap 表中的字形。 如果表中没有字形，则函数指示缺少字形。
ScriptShapeOpenType 在运行中统一地对群集进行排序，在群集中统一地对字形进行排序。 它使用 ScriptItemizeOpenType中 SCRIPT_ANALYSIS的 fRTL 成员的值来确定排序是从左到右还是从右到左。
对于 rpRangeProperties 参数， TEXTRANGE_PROPERTIES 结构指向 OPENTYPE_FEATURE_RECORD 结构的数组。 此数组的使用方式如下：
- 为 rpRangeProperties 指示的数组的每个元素都描述一个范围。
- 共享特定属性的文本范围往往“嵌套”，嵌套跨度可以共享 OPENTYPE_FEATURE_RECORD 信息。 例如，在下图中：
- 顶部的数字行分别表示范围、项和运行。
- 此处用字母标记的每个范围表示单个 OpenType 功能。 属于每个范围的特征存储在该范围的 OPENTYPE_FEATURE_RECORD 数组中。
- 对于每个区域， OPENTYPE_FEATURE_RECORD 结构的数组对应于包含该范围的字母。
- 在此图中，范围 2 间接关联到范围 A、B 和 C 的 OPENTYPE_FEATURE_RECORD 结构。范围 4 仅与范围 A 和 D 的结构相关联。
示例
以下示例演示 ScriptShapeOpenType 如何从 pwcChars) 字符数组 (pwLogClust) 生成逻辑群集数组 (， (pwOutGlyphs) 。 该运行有四个群集。
- 第一个分类：由一个字形表示的一个字符
- 第二个群集：一个字符，由三个字形表示
- 第三个群集：由一个字形表示的三个字符
- 第四个群集：由三个字形表示的两个字符
字符数组：
- |c1u1 |c2u1 |c3u1 c3u2 c3u3 |c4u1 c4u2 |
- |c1g1 |c2g1 c2g2 c2g3 |c3g1 |c4g1 c4g2 c4g3 |
- c<n> 表示群集 n。
- g<m> 表示字形 m。
- u<p> 表示 Unicode 码位 p。
- |0 |1 |4 4 4 |5 5 |
要求
| 最低受支持的客户端 | Windows Vista [仅限桌面应用] |
| 最低受支持的服务器 | Windows Server 2008 [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | usp10.h |
| Library | Usp10.lib |
| DLL | Usp10.dll |
| 可再发行组件 | 在 Windows XP 上 Usp10.dll 版本 1.600 或更高版本 |
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈