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 的单个调用。
如果此函数返回E_OUTOFMEMORY,应用程序可能会使用连续更大的输出缓冲区重复调用 ScriptShapeOpenType ,直到提供足够大的缓冲区。 码位生成的字形数量因脚本和字体而异。 对于简单的脚本,Unicode 码位可能会生成单个字形。 但是,复杂的脚本字体可能会从组件构造字符,从而生成数倍于字符的字形。 此外,还有一些特殊情况,例如无效的字符表示形式,其中添加了额外的字形来表示无效序列。 因此, 对 pwOutGlyphs 指示的缓冲区大小的合理猜测是字符缓冲区长度的 1.5 倍,对于极少数情况(例如,无效序列表示形式),另外还有 16 个字形。

如果字体或操作系统不支持字形索引,则此函数可以设置SCRIPT_ANALYSIS结构的 fNoGlyphIndex 成员。

应用程序可以调用 ScriptShapeOpenType 来确定字体是否支持给定字符串中的字符。 如果函数返回S_OK,则应用程序应检查缺少字形的输出。 如果在SCRIPT_ANALYSIS结构中将 fLogicalOrder 设置为 TRUE,则函数始终按与原始 Unicode 字符相同的顺序生成字形。 如果 fLogicalOrder 设置为 FALSE,则函数将按相反顺序从右到左生成项,以便 ScriptTextOut 在调用 ExtTextOut 之前不必反转它们。

如果 SCRIPT_ANALYSISeScript 成员设置为 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 的许多调用,每个调用都表示一次运行。
 
重要 从 Windows 8 开始:若要保持在 Windows 7 上运行的功能,使用 Uniscribe 的模块必须在其库列表中指定 gdi32.lib 之前的 Usp10.lib。
 

示例

以下示例演示 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 或更高版本

另请参阅

使用 Uniscribe 显示文本

OPENTYPE_FEATURE_RECORD

SCRIPT_ANALYSIS

ScriptItemizeOpenType

ScriptPlaceOpenType

ScriptShape

ScriptTextOut

TEXTRANGE_PROPERTIES

Uniscribe 函数