Fonction ScriptShapeOpenType (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 Remarques.
[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ère, 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 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 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 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 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 les 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.
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 case activée la sortie pour les 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.
ScriptShapeOpenType séquence les clusters de manière uniforme 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 ScriptItemizeOpenType, pour déterminer 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 propriétés particulières de partage de texte ont tendance à « s’imbriquer », et les étendues imbriquées peuvent partager OPENTYPE_FEATURE_RECORD informations. Par exemple, dans l’illustration ci-dessous :
- Les lignes de nombres en haut représentent respectivement des plages, des éléments et des exécutions.
- Chaque étendue étiquetée ici avec une lettre représente une seule fonctionnalité OpenType. Les fonctionnalités qui entrent dans 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.
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 (pwOutGlyphes). L’exécution a 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 :
- | c1u1 | c2u1 | c3u1 c3u2 c3u3 | c4u1 c4u2 |
- | c1g1 | c2g1 c2g2 c2g3 | c3g1 | c4g1 c4g2 c4g3 |
- c<n> signifie cluster n.
- g<m> signifie glyphe m.
- u<p> signifie point de code Unicode p.
- | 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 |