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，應用程式應該檢查輸出中是否有遺漏的字元。如果 fLogicalOrder 在SCRIPT_ANALYSIS結構中設定為 TRUE，則函式一律會以與原始 Unicode 字元相同的順序產生字元。如果 fLogicalOrder 設定為 FALSE，則函式會以反向順序產生由右至左的專案，因此 ScriptTextOut 不需要在呼叫 ExtTextOut 之前加以反轉。

如果 SCRIPT_ANALYSIS 的 eScript 成員設定為 SCRIPT_UNDEFINED，則會停用成形。在此情況下， ScriptShape 會顯示字型 cmap 表格中的圖像。如果數據表中沒有圖像，函式會指出遺漏字元。

ScriptShape 會以統一方式排序執行中的叢集，並在叢集內一致地排序字元。它會使用 scriptItemize 中SCRIPT_ANALYSISfRTL 成員的值，將排序識別為從左至右或由右至左。

重要從 Windows 8 開始：若要維護在 Windows 7 上執行的能力，使用 Uniscribe 的模組必須在其連結庫清單中指定 gdi32.lib 之前指定 Usp10.lib。

範例

下列範例示範 ScriptShape 如何從字元陣列產生邏輯叢集陣列 (pwLogClust) ， (pwcChars) 和字元數位 (pwOutGlyphs) 。執行有四個叢集。

第一個叢集：一個字元以一個字元表示
第二個叢集：以三個字元表示的一個字元
第三個叢集：以一個字元表示的三個字元
第四個叢集：以三個字元表示的兩個字元

字元陣列，其中 c<n>u<m> 表示 cluster n， Unicode 字碼點 m：

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

字元陣列，其中 c<n>g<m> 表示 cluster n， glyph m：

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

叢集陣列，也就是字元中的位移 (，) 到包含字元的叢集：

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

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	usp10.h
程式庫	Usp10.lib
Dll	Usp10.dll