ScriptShapeOpenType-Funktion (usp10.h)

Generiert Glyphen und visuelle Attribute für eine Unicode-Ausführung mit OpenType-Informationen. Jede Ausführung besteht aus einem Aufruf dieser Funktion.

Syntax

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

Parameter

[in, optional] hdc

Handle mit dem Gerätekontext. Weitere Informationen finden Sie unter Zwischenspeichern.

[in, out] psc

Zeiger auf eine SCRIPT_CACHE Struktur, die den Skriptcache identifiziert.

[in, out] psa

Zeiger auf eine SCRIPT_ANALYSIS Struktur, die aus einem vorherigen Aufruf von ScriptItemizeOpenType abgerufen wurde. Die Struktur identifiziert die Formgebungs-Engine, sodass Glyphen korrekt gebildet werden können.

Alternativ kann die Anwendung diesen Parameter auf NULL festlegen, um ungefilterte Ergebnisse zu erhalten.

[in] tagScript

Eine OPENTYPE_TAG Struktur, die das OpenType-Skripttag für das Schreibsystem definiert.

[in] tagLangSys

Eine OPENTYPE_TAG Struktur, die das OpenType-Sprachtag für das Schreibsystem enthält.

[in, optional] rcRangeChars

Array von Zeichen in jedem Bereich. Die Anzahl der Arrayelemente wird durch cRanges angegeben. Die Werte der Elemente dieses Arrays addieren sich zum Wert von cChars.

[in, optional] rpRangeProperties

Array von TEXTRANGE_PROPERTIES Strukturen, die jeweils einen OpenType-Featurebereich darstellen. Die Anzahl der Strukturen wird durch den Parameter cRanges angegeben. Weitere Informationen zu rpRangeProperties finden Sie im Abschnitt Hinweise.

[in] cRanges

Die Anzahl der OpenType-Featurebereiche.

[in] pwcChars

Zeiger auf ein Array von Unicode-Zeichen, das die Ausführung enthält.

[in] cChars

Anzahl der Zeichen in der Unicode-Ausführung.

[in] cMaxGlyphs

Maximale Anzahl von zu generierenden Glyphen.

[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. 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 die Elemente beim Lesen des Arrays abnehmen, wenn das fRTL-Element der SCRIPT_ANALYSIS-StrukturTRUE ist.

[out] pCharProps

Zeiger auf einen Puffer, in dem diese Funktion ein Array von Zeicheneigenschaftenwerten abruft, deren Länge durch cChars angegeben ist.

[out] pwOutGlyphs

Zeiger auf einen Puffer, in dem diese Funktion ein Array von Glyphen abruft.

[out] pOutGlyphProps

Zeiger auf einen Puffer, in dem diese Funktion ein Array von Attributen für jede der abgerufenen Glyphen abruft. Die Länge der Werte entspricht dem Wert von pcGlyphen. Da pro Glyphe eine Glypheneigenschaft angegeben wird, gibt der Wert dieses Parameters die Anzahl der von cMaxGlyphen angegebenen Elemente an.

[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 nichtzero-HRESULT-Wert zurück, wenn er nicht erfolgreich ist. In allen Fehlerfällen ist der Inhalt aller Ausgabearraywerte nicht definiert.

Fehlerrückmeldungen umfassen:

• E_OUTOFMEMORY. Die von cMaxGlyphen angegebene Ausgabepufferlänge reicht nicht aus.
• E_PENDING. Der vom psc-Parameter angegebene Skriptcache enthält nicht genügend Informationen zum Formen der Zeichenfolge, und der Gerätekontext wurde als NULL übergeben, sodass die Funktion den Gestaltungsprozess nicht abschließen kann. Die Anwendung sollte einen richtigen Gerätekontext für die Ausführung einrichten und diese Funktion erneut mit dem entsprechenden Kontextwert in hdc und mit allen anderen Parametern aufrufen.
• USP_E_SCRIPT_NOT_IN_FONT. Die Schriftart, die dem Gerätekontext entspricht, unterstützt das erforderliche Skript nicht. Die Anwendung sollte eine andere Schriftart auswählen und dabei entweder ScriptGetCMap oder eine andere Methode verwenden, um die Schriftart auszuwählen.

Hinweise

ScriptShapeOpenType wird der älteren ScriptShape-Funktion vorgezogen. Einige Vorteile von ScriptShapeOpenType sind:

• Parameter entsprechen direkt OpenType-Tags in Schriftartlayouttabellen.
• Parameter definieren Features, die auf jedes Zeichen angewendet werden.
• Die Eingabe ist in Ausführungen unterteilt. Jede Ausführung verfügt über OpenType-Eigenschaften und besteht aus einem einzelnen Aufruf von ScriptShapeOpenType.

Wenn diese Funktion E_OUTOFMEMORY zurückgibt, ruft die Anwendung ScriptShapeOpenType möglicherweise wiederholt mit nacheinander größeren Ausgabepuffern auf, bis ein ausreichend großer Puffer bereitgestellt ist. 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 erstellen und so mehrmals 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, die von 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 das fNoGlyphIndex-Element der SCRIPT_ANALYSIS-Struktur festlegen, wenn die Schriftart oder das Betriebssystem Glyphenindizes nicht unterstützen können.

Die Anwendung kann ScriptShapeOpenType 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 Glyphen immer in der gleichen 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 diese vor dem Aufrufen von ExtTextOut nicht umkehren muss.

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

ScriptShapeOpenType sequenziert Cluster innerhalb der Ausführung einheitlich und sequenziert Glyphen gleichmäßig innerhalb eines Clusters. Es verwendet den Wert des fRTL-Members von SCRIPT_ANALYSIS aus ScriptItemizeOpenType, um zu ermitteln, ob die Sequenzierung von links nach rechts oder von rechts nach links erfolgt.

Für den parameter rpRangeProperties verweist die TEXTRANGE_PROPERTIES-Struktur auf ein Array von OPENTYPE_FEATURE_RECORD Strukturen. Dieses Array wird wie folgt verwendet:

• Jedes Element des Arrays, das für rpRangeProperties angegeben ist, beschreibt einen Bereich.
• Textspannen, die bestimmte Eigenschaften gemeinsam nutzen, neigen dazu, "zu verschachteln", und geschachtelte Spannen können OPENTYPE_FEATURE_RECORD Informationen freigeben. Beispiel:
  • Die Zahlenzeilen am oberen Rand stellen Bereiche, Elemente und Ausführungen dar.
  • Jede Spanne, die hier mit einem Buchstaben beschriftet ist, stellt ein einzelnes OpenType-Feature dar. Die Features, die in jeden Bereich fallen, werden im OPENTYPE_FEATURE_RECORD Array dieses Bereichs gespeichert.
  • Für jeden Bereich entspricht das Array OPENTYPE_FEATURE_RECORD Strukturen den Buchstaben für die Spannen, die diesen Bereich enthalten.
  • In dieser Abbildung ist Bereich 2 indirekt mit den OPENTYPE_FEATURE_RECORD Strukturen für die Spannen A, B und C verknüpft. Bereich 4 ist nur den Strukturen für die Spannen A und D zugeordnet.

Beispiele

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

• Erster Cluster: Ein Zeichen, das durch eine Glyphe dargestellt wird
• Zweiter Cluster: ein Zeichen, das durch drei Glyphen dargestellt wird
• Dritter Cluster: drei Zeichen, die von einer Glyphe dargestellt werden
• Vierter Cluster: zwei Zeichen, die durch drei Glyphen dargestellt werden

Die Ausführung wird in den Zeichen- und Glyphenarrays wie folgt beschrieben.

Zeichenarray:

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

Glyphenarray:

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

Die Notation für die Arrayelemente besteht aus den folgenden Elementen:

• c<n> bedeutet Cluster n.
• g<m> bedeutet Glyphe m.
• u<p> bedeutet Unicode-Codepunkt p.

Das generierte Clusterarray speichert Offsets für den Cluster, der das Zeichen enthält. Einheiten werden in Glyphen ausgedrückt.

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

Anforderungen

Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	usp10.h
Bibliothek	Usp10.lib
DLL	Usp10.dll
Verteilbare Komponente	Usp10.dll Version 1.600 oder höher unter Windows XP

Weitere Informationen

Anzeigen von Text mit Uniscribe

OPENTYPE_FEATURE_RECORD

SCRIPT_ANALYSIS

ScriptItemizeOpenType

ScriptPlaceOpenType

ScriptShape

ScriptTextOut

TEXTRANGE_PROPERTIES

Uniscribe Functions