ScriptShapeOpenType, fonction (usp10.h)

Génère des glyphes et des attributs visuels pour une exécution Unicode avec des informations OpenType. Chaque exécution se compose d’un appel à cette fonction.

Syntaxe

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

Paramètres

[in, optional] hdc

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, out] psa

Pointeur vers une structure SCRIPT_ANALYSIS obtenue à partir d’un appel précédent à ScriptItemizeOpenType. La structure identifie le moteur de mise en forme, afin que les glyphes puissent être formés correctement.

L’application peut également définir ce paramètre sur NULL pour recevoir des résultats non filtrés.

[in] tagScript

Structure OPENTYPE_TAG définissant la balise de script OpenType pour le système d’écriture.

[in] tagLangSys

Structure OPENTYPE_TAG contenant la balise de langue OpenType pour le système d’écriture.

[in, optional] rcRangeChars

Tableau de caractères dans chaque plage. Le nombre d’éléments de tableau est indiqué par cRanges. Les valeurs des éléments de ce tableau s’ajoutent à la valeur de cChars.

[in, optional] rpRangeProperties

Tableau de structures TEXTRANGE_PROPERTIES , chacune représentant une plage de fonctionnalités OpenType. Le nombre de structures est indiqué par le paramètre cRanges . Pour plus d’informations sur rpRangeProperties, consultez la section Notes.

[in] cRanges

Nombre de plages de fonctionnalités OpenType.

[in] pwcChars

Pointeur vers un tableau de caractères Unicode contenant l’exécution.

[in] cChars

Nombre de caractères dans l’exécution Unicode.

[in] cMaxGlyphs

Nombre maximal de glyphes à générer.

[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. 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 de la structure SCRIPT_ANALYSIS a la valeur TRUE, les éléments diminuent à mesure que le tableau est lu.

[out] pCharProps

Pointeur vers une mémoire tampon dans laquelle cette fonction récupère un tableau de valeurs de propriété de caractères, de longueur indiquée par cChars.

[out] pwOutGlyphs

Pointeur vers une mémoire tampon dans laquelle cette fonction récupère un tableau de glyphes.

[out] pOutGlyphProps

Pointeur vers une mémoire tampon dans laquelle cette fonction récupère un tableau d’attributs pour chacun des glyphes récupérés. La longueur des valeurs est égale à la valeur des pcGlyphes. Étant donné qu’une propriété de glyphe est indiquée par glyphe, la valeur de ce paramètre indique le nombre d’éléments spécifiés par cMaxGlyphes.

[out] pcGlyphs

Pointeur vers l’emplacement dans lequel cette fonction récupère le nombre de glyphes indiqués dans pwOutGlyphs.

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 toutes les valeurs de tableau 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 les 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 de contexte 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. L’application doit choisir une autre police, à l’aide de ScriptGetCMap ou d’une autre méthode pour sélectionner la police.

Remarques

ScriptShapeOpenType est préféré à l’ancienne fonction ScriptShape . Voici quelques avantages de ScriptShapeOpenType :

  • Les paramètres correspondent directement aux balises OpenType dans les tables de disposition de police.
  • Les paramètres définissent des fonctionnalités appliquées à chaque caractère.
  • L’entrée est divisée en exécutions. Chaque exécution a des propriétés OpenType et se compose d’un seul appel à ScriptShapeOpenType.
Si cette fonction retourne E_OUTOFMEMORY, l’application peut appeler ScriptShapeOpenType à plusieurs reprises, avec des mémoires tampons de sortie successivement plus volumineuses, jusqu’à ce qu’une mémoire tampon suffisante 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 glyphe unique. Toutefois, une police de script complexe peut construire des caractères à partir de composants, et donc générer plusieurs fois plus de glyphes que de caractères. Il existe également 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, plus un 16 glyphes supplémentaire pour les cas rares, 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 glyphe.

L’application peut appeler ScriptShapeOpenType 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 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, ScriptShapeOpenType 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.

Les séquences ScriptShapeOpenType sont uniformément au sein de l’exécution, et les glyphes s’exécutent uniformément au sein d’un cluster. Il utilise la valeur du membre fRTL de SCRIPT_ANALYSIS, de ScriptItemizeOpenType, pour identifier si le séquencement est de gauche à droite ou de droite à gauche.

Pour le paramètre rpRangeProperties , la structure TEXTRANGE_PROPERTIES pointe vers un tableau de structures OPENTYPE_FEATURE_RECORD . Ce tableau est utilisé comme suit :

  • Chaque élément du tableau indiqué pour rpRangeProperties décrit une plage.
  • Les étendues de partage de texte en particulier ont tendance à « imbriquer » et les étendues imbriquées peuvent partager des informations OPENTYPE_FEATURE_RECORD . Par exemple, dans l’illustration ci-dessous :
    • Les lignes de nombres situées en haut représentent respectivement les plages, les éléments et les exécutions.
    • Chaque étendue étiquetée ici avec une lettre représente une seule fonctionnalité OpenType. Les fonctionnalités qui appartiennent à chaque plage sont stockées dans le tableau OPENTYPE_FEATURE_RECORD de cette plage.
    • Pour chaque plage, le tableau de structures OPENTYPE_FEATURE_RECORD correspond aux lettres des étendues qui contiennent cette plage.
    • Dans cette illustration, la plage 2 est indirectement associée aux structures OPENTYPE_FEATURE_RECORD pour les étendues A, B et C. La plage 4 est associée uniquement aux structures des étendues A et D.
Illustration montrant la plage, l’élément, l’exécution et la fonctionnalité de chaque mot dans une ligne de texte qui utilise six propriétés pour présenter huit mots
Note L’illustration utilise de nombreux appels à ScriptShapeOpenType, chacun représentant une exécution.
 
Important À compter de Windows 8 : pour maintenir la possibilité d’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 ScriptShapeOpenType génère un tableau de cluster logique (pwLogClust) à partir d’un tableau de caractères (pwcChars) et d’un tableau de glyphes (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
L’exécution est décrite comme suit dans les tableaux de caractères et de glyphes.

Tableau de caractères :

  • | c1u1 | c2u1 | c3u1 c3u2 c3u3 | c4u1 c4u2 |
Tableau de Glyphes :
  • | c1g1 | c2g1 c2g2 c2g3 | c3g1 | c4g1 c4g2 c4g3 |
La notation pour les éléments de tableau se compose de ces éléments :
  • c<n> signifie cluster n.
  • g<m> signifie glyphe m.
  • u<p> signifie le point de code Unicode p.
Le tableau de clusters généré stocke les décalages vers le cluster contenant le caractère. Les unités sont exprimées en glyphes.
  • | 0 | 1 | 4 4 4 | 5 5 |

Configuration requise

   
Client minimal pris en charge Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2008 [applications de bureau uniquement]
Plateforme cible Windows
En-tête usp10.h
Bibliothèque Usp10.lib
DLL Usp10.dll
Composant redistribuable Usp10.dll version 1.600 ou ultérieure sur Windows XP

Voir aussi

Affichage du texte avec l’inscription unicrite

OPENTYPE_FEATURE_RECORD

SCRIPT_ANALYSIS

ScriptItemizeOpenType

ScriptPlaceOpenType

ScriptShape

ScriptTextOut

TEXTRANGE_PROPERTIES

Fonctions uniscribe