ScriptShape 函数 (usp10.h)

项目
03/03/2024

为 Unicode 运行生成字形和可视属性。

语法

HRESULT ScriptShape(
  [in]      HDC             hdc,
  [in, out] SCRIPT_CACHE    *psc,
  [in]      const WCHAR     *pwcChars,
  [in]      int             cChars,
  [in]      int             cMaxGlyphs,
  [in, out] SCRIPT_ANALYSIS *psa,
  [out]     WORD            *pwOutGlyphs,
  [out]     WORD            *pwLogClust,
  [out]     SCRIPT_VISATTR  *psva,
  [out]     int             *pcGlyphs
);

参数

[in] hdc

可选。设备上下文的句柄。有关详细信息，请参阅缓存。

[in, out] psc

指向标识脚本缓存的SCRIPT_CACHE 结构的指针。

[in] pwcChars

指向定义运行的 Unicode 字符数组的指针。

[in] cChars

Unicode 运行中的字符数。

[in] cMaxGlyphs

要生成的最大字形数和 pwOutGlyphs 的长度。合理的值为 (1.5 * cChars + 16)，但在某些情况下，此值可能不足。有关详细信息，请参见“备注”部分。

[in, out] psa

指向运行的 SCRIPT_ANALYSIS 结构的指针，其中包含之前对 ScriptItemize 的调用的结果。

[out] pwOutGlyphs

指向缓冲区的指针，此函数在其中检索具有 cMaxGlyphs 指示大小的字形数组。

[out] pwLogClust

指向缓冲区的指针，此函数在其中检索逻辑群集信息数组。每个数组元素对应于 Unicode 字符数组中的一个字符;因此，此数组具有 cChars 指示的元素数。每个元素的值都是从运行中的第一个字形到包含相应字符的群集中第一个字形的偏移量。请注意，当 fRTL 成员在SCRIPT_ANALYSIS结构中设置为 TRUE 时，元素会随着数组的读取而减少。

[out] psva

指向缓冲区的指针，此函数在其中检索包含可视属性信息的 SCRIPT_VISATTR 结构数组。由于每个字形只有一个可视属性，因此此数组具有 cMaxGlyphs 指示的元素数。

[out] pcGlyphs

指向此函数检索 pwOutGlyphs 中指示的字形数的位置的指针。

返回值

如果成功，则返回 0。如果函数不成功，则返回非零 HRESULT 值。在所有错误情况下，所有输出参数的内容都是未定义的。

错误返回包括：

E_OUTOFMEMORY。 cMaxGlyphs 指示的输出缓冲区长度不足。
E_PENDING。 psc 参数指定的脚本缓存不包含足够的信息来调整字符串，并且设备上下文已作为 NULL 传递，因此函数无法完成整形过程。应用程序应为运行设置正确的设备上下文，并使用 hdc 中的相应值和所有其他参数相同再次调用此函数。
USP_E_SCRIPT_NOT_IN_FONT。与设备上下文对应的字体不支持 pwcChars 指示的运行所需的脚本。应用程序应选择另一种字体，使用 ScriptGetCMap 或其他函数来选择字体。

注解

有关通常调用此函数的上下文的讨论，请参阅使用 Uniscribe 显示文本。

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

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

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

如果 SCRIPT_ANALYSIS 的 eScript 成员设置为 SCRIPT_UNDEFINED，则禁用整形。在这种情况下， ScriptShape 显示字体 cmap 表中的字形。如果表中没有字形，则函数指示缺少字形。

ScriptShape 在运行中统一地对群集进行排序，并在群集中统一地对字形进行排序。它使用 ScriptItemize 中 SCRIPT_ANALYSIS 的 fRTL 成员的值将排序标识为从左到右或从右到左。

重要从Windows 8开始：若要保持在 Windows 7 上运行的功能，使用 Uniscribe 的模块必须在其库列表中指定 gdi32.lib 之前的 Usp10.lib。

示例

以下示例演示 ScriptShape 如何从 pwcChars) 字符数组 (pwLogClust) 生成逻辑群集 (数组 (pwOutGlyphs) 。该运行有四个群集。

第一个分类：由一个字形表示的一个字符
第二个群集：一个字符，由三个字形表示
第三个群集：由一个字形表示的三个字符
第四个群集：由三个字形表示的两个字符

字符数组，其中 c<n>u<m> 表示群集 n，Unicode 码位 m：

|c1u1 |c2u1 |c3u1 c3u2 c3u3 |c4u1 c4u2 |

字形数组，其中 c<n>g<m> 表示群集 n，字形 m：

|c1g1 |c2g1 c2g2 c2g3 |c3g1 |c4g1 c4g2 c4g3 |

群集数组，即字形中的偏移量 () 包含字符的群集：

|0 |1 |4 4 4 |5 5 |

要求

要求	值
最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	usp10.h
Library	Usp10.lib
DLL	Usp10.dll