Fonction ScriptShape (usp10.h)
Génère des glyphes et des attributs visuels pour une exécution Unicode.
Syntaxe
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
);
Paramètres
[in] hdc
Facultatif. Gérez le contexte de l’appareil. Pour plus d’informations, consultez Mise en cache.
[in, out] psc
Pointeur vers une structure SCRIPT_CACHE identifiant le cache de script.
[in] pwcChars
Pointeur vers un tableau de caractères Unicode définissant l’exécution.
[in] cChars
Nombre de caractères dans l’exécution Unicode.
[in] cMaxGlyphs
Nombre maximal de glyphes à générer et longueur des pwOutGlyphes. Une valeur raisonnable est (1.5 * cChars + 16), mais cette valeur peut être insuffisante dans certaines circonstances. Pour plus d'informations, consultez la section Notes.
[in, out] psa
Pointeur vers la structure SCRIPT_ANALYSIS de l’exécution, contenant les résultats d’un appel antérieur à ScriptItemize.
[out] pwOutGlyphs
Pointeur vers une mémoire tampon dans laquelle cette fonction récupère un tableau de glyphes de taille, comme indiqué par cMaxGlyphes.
[out] pwLogClust
Pointeur vers une mémoire tampon dans laquelle cette fonction récupère un tableau d’informations de cluster logique. Chaque élément de tableau correspond à un caractère dans le tableau de caractères Unicode ; Par conséquent, ce tableau a le nombre d’éléments indiqué par cChars. La valeur de chaque élément est le décalage entre le premier glyphe de l’exécution et le premier glyphe du cluster contenant le caractère correspondant. Notez que, lorsque le membre fRTL est défini sur TRUE dans la structure SCRIPT_ANALYSIS , les éléments diminuent à mesure que le tableau est lu.
[out] psva
Pointeur vers une mémoire tampon dans laquelle cette fonction récupère un tableau de structures SCRIPT_VISATTR contenant des informations d’attribut visuel. Étant donné que chaque glyphe n’a qu’un seul attribut visuel, ce tableau a le nombre d’éléments indiqué par les cMaxGlyphes.
[out] pcGlyphs
Pointeur vers l’emplacement où cette fonction récupère le nombre de glyphes indiqués dans pwOutGlyphes.
Valeur retournée
Retourne 0 en cas de réussite. La fonction retourne une valeur HRESULT différente de zéro si elle ne réussit pas. Dans tous les cas d’erreur, le contenu de tous les paramètres de sortie n’est pas défini.
Les retours d’erreur incluent :
- E_OUTOFMEMORY. La longueur de la mémoire tampon de sortie indiquée par cMaxGlyphes est insuffisante.
- E_PENDING. Le cache de script spécifié par le paramètre psc ne contient pas suffisamment d’informations pour mettre en forme la chaîne, et le contexte de l’appareil a été passé comme NULL de sorte que la fonction ne peut pas terminer le processus de mise en forme. L’application doit configurer un contexte d’appareil correct pour l’exécution et appeler à nouveau cette fonction avec la valeur appropriée dans hdc et avec tous les autres paramètres identiques.
- USP_E_SCRIPT_NOT_IN_FONT. La police correspondant au contexte de l’appareil ne prend pas en charge le script requis par l’exécution indiquée par pwcChars. L’application doit choisir une autre police, à l’aide de ScriptGetCMap ou d’une autre fonction pour sélectionner la police.
Remarques
Consultez Affichage de texte avec uniscribe pour une présentation du contexte dans lequel cette fonction est normalement appelée.
Si cette fonction retourne E_OUTOFMEMORY, l’application peut appeler ScriptShape à plusieurs reprises, avec des mémoires tampons de sortie successivement plus grandes, jusqu’à ce qu’une mémoire tampon suffisamment grande soit fournie. Le nombre de glyphes générés par un point de code varie en fonction du script et de la police. Pour un script simple, un point de code Unicode peut générer un seul glyphe. Toutefois, une police de script complexe peut construire des caractères à partir de composants et générer ainsi plusieurs fois plus de glyphes que de caractères. En outre, il existe des cas spéciaux, tels que des représentations de caractères non valides, dans lesquels des glyphes supplémentaires sont ajoutés pour représenter la séquence non valide. Par conséquent, une estimation raisonnable de la taille de la mémoire tampon indiquée par pwOutGlyphes est de 1,5 fois la longueur de la mémoire tampon de caractères, plus 16 glyphes supplémentaires dans de rares cas, par exemple, une représentation séquentielle non valide.
Cette fonction peut définir le membre fNoGlyphIndex de la structure SCRIPT_ANALYSIS si la police ou le système d’exploitation ne peut pas prendre en charge les index de glyphes.
L’application peut appeler ScriptShape pour déterminer si une police prend en charge les caractères d’une chaîne donnée. Si la fonction retourne S_OK, l’application doit case activée la sortie des glyphes manquants. Si fLogicalOrder est défini sur TRUE dans la structure SCRIPT_ANALYSIS , la fonction génère toujours des glyphes dans le même ordre que les caractères Unicode d’origine. Si fLogicalOrder a la valeur FALSE, la fonction génère des éléments de droite à gauche dans l’ordre inverse afin que ScriptTextOut n’ait pas à les inverser avant d’appeler ExtTextOut.
Si le membre eScript de SCRIPT_ANALYSIS est défini sur SCRIPT_UNDEFINED, la mise en forme est désactivée. Dans ce cas, ScriptShape affiche le glyphe qui se trouve dans la table cmap de police. Si aucun glyphe n’est dans la table, la fonction indique que les glyphes sont manquants.
ScriptShape séquence les clusters uniformément au sein de l’exécution, et séquence uniformément les glyphes au sein d’un cluster. Il utilise la valeur du membre fRTL de SCRIPT_ANALYSIS, de ScriptItemize, pour identifier le séquencement comme étant de gauche à droite ou de droite à gauche.
Exemples
L’exemple suivant montre comment ScriptShape génère un tableau de cluster logique (pwLogClust) à partir d’un tableau de caractères (pwcChars) et d’un tableau de glyphes (pwOutGlyphes). L’exécution comporte quatre clusters.
- Premier cluster : un caractère représenté par un glyphe
- Deuxième cluster : un caractère représenté par trois glyphes
- Troisième cluster : trois caractères représentés par un glyphe
- Quatrième cluster : deux caractères représentés par trois glyphes
- | c1u1 | c2u1 | c3u1 c3u2 c3u3 | c4u1 c4u2 |
- | c1g1 | c2g1 c2g2 c2g3 | c3g1 | c4g1 c4g2 c4g3 |
- | 0 | 1 | 4 4 4 | 5 5 |
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows 2000 Professionnel [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows 2000 Server [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | usp10.h |
| Bibliothèque | Usp10.lib |
| DLL | Usp10.dll |