Freigeben über


ScriptShape-Funktion (usp10.h)

Generiert Glyphen und visuelle Attribute für eine Unicode-Ausführung.

Syntax

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
);

Parameter

[in] hdc

Optional. Handle für den Gerätekontext. Weitere Informationen finden Sie unter Zwischenspeichern.

[in, out] psc

Zeiger auf eine SCRIPT_CACHE Struktur, die den Skriptcache identifiziert.

[in] pwcChars

Zeiger auf ein Array von Unicode-Zeichen, das die Ausführung definiert.

[in] cChars

Anzahl der Zeichen in der Unicode-Ausführung.

[in] cMaxGlyphs

Maximale Anzahl der zu generierenden Glyphen und länge von pwOutGlyphen. Ein vernünftiger Wert ist (1.5 * cChars + 16), aber dieser Wert kann unter bestimmten Umständen nicht ausreichen. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

[in, out] psa

Zeiger auf die SCRIPT_ANALYSIS-Struktur für die Ausführung, die die Ergebnisse eines früheren Aufrufs von ScriptItemize enthält.

[out] pwOutGlyphs

Zeiger auf einen Puffer, in dem diese Funktion ein Array von Glyphen mit größe abruft, wie durch cMaxGlyphen angegeben.

[out] pwLogClust

Zeiger auf einen Puffer, in dem diese Funktion ein Array logischer Clusterinformationen abruft. Jedes Arrayelement entspricht einem Zeichen im Array von Unicode-Zeichen; daher weist dieses Array die Anzahl von Elementen auf, die durch cChars angegeben werden. Der Wert jedes Elements ist der Offset von der ersten Glyphe in der Ausführung bis zur ersten Glyphe im Cluster, die das entsprechende Zeichen enthält. Beachten Sie, dass, wenn der fRTL-Member in der SCRIPT_ANALYSIS-Struktur auf TRUE festgelegt ist, die Elemente abnehmen, wenn das Array gelesen wird.

[out] psva

Zeiger auf einen Puffer, in dem diese Funktion ein Array von SCRIPT_VISATTR Strukturen abruft, die visuelle Attributinformationen enthalten. Da jede Glyphe nur über ein visuelles Attribut verfügt, verfügt dieses Array über die Anzahl von Elementen, die durch cMaxGlyphen angegeben werden.

[out] pcGlyphs

Zeiger auf die Position, an der diese Funktion die Anzahl der in pwOutGlyphen angegebenen Glyphen abruft.

Rückgabewert

Gibt bei Erfolg 0 zurück. Die Funktion gibt einen HRESULT-Wert ungleich null zurück, wenn sie nicht erfolgreich ist. In allen Fehlerfällen ist der Inhalt aller Ausgabeparameter nicht definiert.

Fehlerrückmeldungen umfassen:

  • E_OUTOFMEMORY. Die durch cMaxGlyphen angegebene Länge des Ausgabepuffers reicht nicht aus.
  • E_PENDING. Der vom psc-Parameter angegebene Skriptcache enthält nicht genügend Informationen, um die Zeichenfolge zu formen, und der Gerätekontext wurde als NULL übergeben, sodass die Funktion den Strukturierungsprozess nicht abschließen kann. Die Anwendung sollte einen richtigen Gerätekontext für die Ausführung einrichten und diese Funktion erneut mit dem entsprechenden Wert in hdc und allen anderen Parametern aufrufen.
  • USP_E_SCRIPT_NOT_IN_FONT. Die Schriftart, die dem Gerätekontext entspricht, unterstützt nicht das Skript, das für die ausführung erforderlich ist, die von pwcChars angegeben wird. Die Anwendung sollte eine andere Schriftart auswählen und dabei entweder ScriptGetCMap oder eine andere Funktion verwenden, um die Schriftart auszuwählen.

Hinweise

Eine Erläuterung des Kontexts, in dem diese Funktion normalerweise aufgerufen wird, finden Sie unter Anzeigen von Text mit Uniscribe .

Wenn diese Funktion E_OUTOFMEMORY zurückgibt, ruft die Anwendung ScriptShape möglicherweise wiederholt mit nacheinander größeren Ausgabepuffern auf, bis ein ausreichend großer Puffer bereitgestellt wird. Die Anzahl der von einem Codepunkt generierten Glyphen variiert je nach Skript und Schriftart. Für ein einfaches Skript kann ein Unicode-Codepunkt eine einzelne Glyphe generieren. Eine komplexe Skriptschriftart kann jedoch Zeichen aus Komponenten konstruieren und somit mehrfach so viele Glyphen wie Zeichen generieren. Außerdem gibt es Sonderfälle, z. B. ungültige Zeichendarstellungen, in denen zusätzliche Glyphen hinzugefügt werden, um die ungültige Sequenz darzustellen. Daher ist eine vernünftige Schätzung für die Größe des Puffers, der durch pwOutGlyphen angegeben wird, das 1,5-fache der Länge des Zeichenpuffers, plus zusätzliche 16 Glyphen für seltene Fälle, z. B. ungültige Sequenzdarstellung.

Diese Funktion kann den fNoGlyphIndex-Member der SCRIPT_ANALYSIS-Struktur festlegen, wenn die Schriftart oder das Betriebssystem Glyphenindizes nicht unterstützen kann.

Die Anwendung kann ScriptShape aufrufen, um zu bestimmen, ob eine Schriftart die Zeichen in einer bestimmten Zeichenfolge unterstützt. Wenn die Funktion S_OK zurückgibt, sollte die Anwendung die Ausgabe auf fehlende Glyphen überprüfen. Wenn fLogicalOrder in der SCRIPT_ANALYSIS-Struktur auf TRUE festgelegt ist, generiert die Funktion immer Glyphen in derselben Reihenfolge wie die ursprünglichen Unicode-Zeichen. Wenn fLogicalOrder auf FALSE festgelegt ist, generiert die Funktion Elemente von rechts nach links in umgekehrter Reihenfolge, sodass ScriptTextOut sie vor dem Aufruf von ExtTextOut nicht umkehren muss.

Wenn das eScript-Element von SCRIPT_ANALYSIS auf SCRIPT_UNDEFINED festgelegt ist, wird die Strukturierung deaktiviert. In diesem Fall zeigt ScriptShape die Glyphe an, die sich in der CMAP-Tabelle der Schriftart befindet. Wenn keine Glyphe in der Tabelle enthalten ist, gibt die Funktion an, dass Glyphen fehlen.

ScriptShape sequenziert Cluster innerhalb der Ausführung einheitlich und sequenziert Glyphen einheitlich innerhalb eines Clusters. Es verwendet den Wert des fRTL-Elements von SCRIPT_ANALYSIS aus ScriptItemize, um die Sequenzierung als von links nach rechts oder von rechts nach links zu identifizieren.

Wichtig Ab Windows 8: Um die Ausführung unter Windows 7 zu gewährleisten, muss ein Modul, das Uniscribe verwendet, Usp10.lib vor gdi32.lib in der Bibliotheksliste angeben.
 

Beispiele

Das folgende Beispiel zeigt, wie ScriptShape ein logisches Clusterarray (pwLogClust) aus einem Zeichenarray (pwcChars) und einem Glyphenarray (pwOutGlyphen) generiert. Die Ausführung umfasst vier Cluster.

  • Erster Cluster: Ein Zeichen, dargestellt durch eine Glyphe
  • Zweiter Cluster: ein Zeichen, dargestellt durch drei Glyphen
  • Dritter Cluster: drei Zeichen, dargestellt durch eine Glyphe
  • Vierter Cluster: zwei Zeichen, dargestellt durch drei Glyphen
Zeichenarray, wobei c<n>u<m> für Cluster n steht, Unicode-Codepunkt m:
  • | c1u1 | c2u1 | c3u1 c3u2 c3u3 | c4u1 c4u2 |
Glyphenarray, wobei c<n>g<m> cluster n, glyph m bedeutet:
  • | c1g1 | c2g1 c2g2 c2g3 | c3g1 | c4g1 c4g2 c4g3 |
Clusterarray, d. h. der Offset (in Glyphen) zu dem Cluster, der das Zeichen enthält:
  • | 0 | 1 | 4 4 4 | 5 5 |

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows 2000 Server [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile usp10.h
Bibliothek Usp10.lib
DLL Usp10.dll

Weitere Informationen

Anzeigen von Text mit Uniscribe

SCRIPT_ANALYSIS

SCRIPT_CACHE

SCRIPT_VISATTR

ScriptItemize

ScriptShapeOpenType

ScriptTextOut

Uniscribe

Uniscribe-Funktionen