ScriptShape, fonction (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 la 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 les 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 contient le nombre d’éléments indiqués par cChars. La valeur de chaque élément est le décalage du premier glyphe de l’exécution au premier glyphe dans le cluster contenant le caractère correspondant. Notez que, lorsque le membre fRTL a la valeur TRUE dans la structure SCRIPT_ANALYSIS , les éléments diminuent lorsque 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és par cMaxGlyphes.

[out] pcGlyphs

Pointeur vers l’emplacement dans lequel 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 sont les suivants :

  • 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 afin que la fonction ne puisse 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 discussion sur le 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 suffisante soit fournie. Le nombre de glyphes générés par un point de code varie selon le script et la police. Pour un script simple, un point de code Unicode peut générer un glyphe unique. Toutefois, une police de script complexe peut construire des caractères à partir de composants, et ainsi générer 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 pwOutGlyphs est de 1,5 fois la longueur de la mémoire tampon de caractères, ainsi qu’un nombre supplémentaire de 16 glyphes pour les cas rares, par exemple, une représentation de séquence 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 glyphe.

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 vérifier la sortie des glyphes manquants. Si fLogicalOrder a la valeur 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 est défini sur 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 les séquences glyphes uniformément au sein d’un cluster. Il utilise la valeur du membre fRTL de SCRIPT_ANALYSIS, de ScriptItemize, pour identifier le séquencement comme de gauche à droite ou de droite à gauche.

Important À compter de Windows 8 : pour maintenir la capacité à 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 glyphe (pwOutGlyphs). 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 Glyphe, où c<n g<m> signifie cluster n>, glyphe m :
  • | c1g1 | c2g1 c2g2 c2g3 | c3g1 | c4g1 c4g2 c4g3 |
Tableau de cluster, autrement dit, décalage (en glyphes) vers le cluster contenant le caractère :
  • | 0 | 1 | 4 4 4 | 5 5 |

Configuration requise

   
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

Voir aussi

Affichage du texte avec l’inscription unicrite

SCRIPT_ANALYSIS

SCRIPT_CACHE

SCRIPT_VISATTR

ScriptItemize

ScriptShapeOpenType

ScriptTextOut

Annuler l’inscription

Fonctions monocrites