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

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

ScriptShapeOpenType 會在執行中統一排序叢集，並一致地排序叢集內的字元。 它會使用ScriptItemizeOpenType中SCRIPT_ANALYSISfRTL成員的值，來識別排序是否由左至右或由右至左。

針對 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 的模組必須在其程式庫清單中指定 Usp10.lib 之前，才能指定 Usp32.lib。

 

範例

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

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

執行描述如下字元和字元陣列。

字元陣列：

• |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
程式庫	Usp10.lib
Dll	Usp10.dll
可轉散發套件	在 Windows XP 上 Usp10.dll 1.600 版或更新版本

另請參閱

使用 Uniscribe 顯示文字

OPENTYPE_FEATURE_RECORD

SCRIPT_ANALYSIS

ScriptItemizeOpenType

ScriptPlaceOpenType

ScriptShape

ScriptTextOut

TEXTRANGE_PROPERTIES

Uniscribe 函式