Fonction ScriptShape (usp10.h)

Article
03/06/2024

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.

Important À compter de Windows 8 : pour conserver la possibilité de s’exécuter sur Windows 7, un module qui utilise Uniscribe doit spécifier Usp10.lib avant gdi32.lib dans sa liste de bibliothèques.

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

Tableau de caractères, où c<n>u<m> signifie cluster n, point de code Unicode m :

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

Tableau de glyphes, où c<n>g<m> signifie cluster n, glyphe m :

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

Tableau de cluster, c’est-à-dire le décalage (en glyphes) sur le cluster contenant le caractère :

| 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