Funzione ScriptShapeOpenType (usp10.h)
Genera glifi e attributi visivi per un'esecuzione Unicode con informazioni OpenType. Ogni esecuzione è costituita da una chiamata a questa funzione.
Sintassi
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
);
Parametri
[in, optional] hdc
Gestire nel contesto del dispositivo. Per altre informazioni, vedere Memorizzazione nella cache.
[in, out] psc
Puntatore a una struttura SCRIPT_CACHE che identifica la cache degli script.
[in, out] psa
Puntatore a una struttura SCRIPT_ANALYSIS ottenuta da una chiamata precedente a ScriptItemizeOpenType. La struttura identifica il motore di modellazione, in modo che i glifi possano essere formati correttamente.
In alternativa, l'applicazione può impostare questo parametro su NULL per ricevere risultati non filtrati.
[in] tagScript
Struttura OPENTYPE_TAG che definisce il tag di script OpenType per il sistema di scrittura.
[in] tagLangSys
Struttura OPENTYPE_TAG contenente il tag di lingua OpenType per il sistema di scrittura.
[in, optional] rcRangeChars
Matrice di caratteri in ogni intervallo. Il numero di elementi della matrice è indicato da cRanges. I valori degli elementi di questa matrice vengono aggiunti al valore di cChars.
[in, optional] rpRangeProperties
Matrice di strutture TEXTRANGE_PROPERTIES , ognuna che rappresenta un intervallo di funzionalità OpenType. Il numero di strutture è indicato dal parametro cRanges . Per altre informazioni su rpRangeProperties, vedere la sezione Osservazioni.
[in] cRanges
Numero di intervalli di funzionalità OpenType.
[in] pwcChars
Puntatore a una matrice di caratteri Unicode contenente l'esecuzione.
[in] cChars
Numero di caratteri nell'esecuzione Unicode.
[in] cMaxGlyphs
Numero massimo di glifi da generare.
[out] pwLogClust
Puntatore a un buffer in cui questa funzione recupera una matrice di informazioni sul cluster logico. Ogni elemento della matrice corrisponde a un carattere nella matrice di caratteri Unicode. Il valore di ogni elemento è l'offset dal primo glifo nell'esecuzione al primo glifo nel cluster contenente il carattere corrispondente. Si noti che, quando il membro fRTL della struttura SCRIPT_ANALYSIS è TRUE, gli elementi diminuiscono man mano che la matrice viene letta.
[out] pCharProps
Puntatore a un buffer in cui questa funzione recupera una matrice di valori di proprietà carattere, di lunghezza indicata da cChars.
[out] pwOutGlyphs
Puntatore a un buffer in cui questa funzione recupera una matrice di glifi.
[out] pOutGlyphProps
Puntatore a un buffer in cui questa funzione recupera una matrice di attributi per ognuno dei glifi recuperati. La lunghezza dei valori è uguale al valore di pcGlyphs. Poiché una proprietà glifo è indicata per ogni glifo, il valore di questo parametro indica il numero di elementi specificati da cMaxGlyphs.
[out] pcGlyphs
Puntatore alla posizione in cui questa funzione recupera il numero di glifi indicati in pwOutGlyphs.
Valore restituito
Restituisce 0 in caso di esito positivo. Se non ha esito positivo, la funzione restituisce un valore HRESULT diverso da zero. In tutti i casi di errore, il contenuto di tutti i valori della matrice di output non è definito.
I valori restituiti dall'errore includono:
- E_OUTOFMEMORY. La lunghezza del buffer di output indicata da cMaxGlyphs non è sufficiente.
- E_PENDING. La cache di script specificata dal parametro psc non contiene informazioni sufficienti per modellare la stringa e il contesto del dispositivo è stato passato come NULL in modo che la funzione non sia in grado di completare il processo di shaping. L'applicazione deve configurare un contesto di dispositivo corretto per l'esecuzione e chiamare di nuovo questa funzione con il valore di contesto appropriato in hdc e con tutti gli altri parametri uguali.
- USP_E_SCRIPT_NOT_IN_FONT. Il tipo di carattere corrispondente al contesto di dispositivo non supporta lo script richiesto. L'applicazione deve scegliere un altro tipo di carattere, usando ScriptGetCMap o un altro metodo per selezionare il tipo di carattere.
Commenti
ScriptShapeOpenType è preferibile rispetto alla funzione ScriptShape precedente. Di seguito sono riportati alcuni vantaggi di ScriptShapeOpenType :
- I parametri corrispondono direttamente ai tag OpenType nelle tabelle di layout dei tipi di carattere.
- I parametri definiscono le funzionalità applicate a ogni carattere.
- L'input è suddiviso in esecuzioni. Ogni esecuzione ha proprietà OpenType ed è costituita da una singola chiamata a ScriptShapeOpenType.
Questa funzione può impostare il membro fNoGlyphIndex della struttura SCRIPT_ANALYSIS se il tipo di carattere o il sistema operativo non può supportare gli indici glifi.
L'applicazione può chiamare ScriptShapeOpenType per determinare se un tipo di carattere supporta i caratteri in una determinata stringa. Se la funzione restituisce S_OK, l'applicazione deve verificare la presenza di glifi mancanti nell'output. Se fLogicalOrder è impostato su TRUE nella struttura SCRIPT_ANALYSIS , la funzione genera sempre glifi nello stesso ordine dei caratteri Unicode originali. Se fLogicalOrder è impostato su FALSE, la funzione genera elementi da destra a sinistra in ordine inverso in modo che ScriptTextOut non sia necessario annullarli prima di chiamare ExtTextOut.
Se il membro eScript di SCRIPT_ANALYSIS è impostato su SCRIPT_UNDEFINED, il data shaping è disabilitato. In questo caso , ScriptShapeOpenType visualizza il glifo presente nella tabella cmap del tipo di carattere. Se nella tabella non è presente alcun glifo, la funzione indica che mancano i glifi.
ScriptShapeOpenType sequenza cluster in modo uniforme all'interno dell'esecuzione e sequenze glifi in modo uniforme all'interno di un cluster. Usa il valore del membro fRTL di SCRIPT_ANALYSIS, da ScriptItemizeOpenType, per identificare se la sequenziazione è da sinistra a destra o da destra a sinistra.
Per il parametro rpRangeProperties , la struttura TEXTRANGE_PROPERTIES punta a una matrice di strutture OPENTYPE_FEATURE_RECORD . Questa matrice viene usata come segue:
- Ogni elemento della matrice indicato per rpRangeProperties descrive un intervallo.
- Gli intervalli di condivisione del testo tendono a "annidare" e gli intervalli annidati possono condividere OPENTYPE_FEATURE_RECORD informazioni. Nell'illustrazione seguente, ad esempio:
- Le righe di numeri nella parte superiore rappresentano rispettivamente intervalli, elementi e esecuzioni.
- Ogni intervallo etichettato qui con una lettera rappresenta una singola funzionalità OpenType. Le funzionalità che rientrano in ogni intervallo vengono archiviate nella matrice OPENTYPE_FEATURE_RECORD di tale intervallo.
- Per ogni intervallo, la matrice di strutture OPENTYPE_FEATURE_RECORD corrisponde alle lettere per gli intervalli che contengono tale intervallo.
- In questa illustrazione l'intervallo 2 è associato indirettamente alle strutture di OPENTYPE_FEATURE_RECORD per gli intervalli A, B e C. L'intervallo 4 è associato solo alle strutture per gli intervalli A e D.
Esempio
L'esempio seguente mostra come ScriptShapeOpenType genera una matrice di cluster logici (pwLogClust) da una matrice di caratteri (pwcChars) e una matrice di glifi (pwOutGlyphs). L'esecuzione ha quattro cluster.
- Primo cluster: un carattere rappresentato da un glifo
- Secondo cluster: un carattere rappresentato da tre glifi
- Terzo cluster: tre caratteri rappresentati da un glifo
- Quarto cluster: due caratteri rappresentati da tre glifi
Matrice di caratteri:
- | c1u1 | c2u1 | c3u1 c3u2 c3u3 | c4u1 c4u2 |
- | c1g1 | c2g1 c2g2 c2g3 | c3g1 | c4g1 c4g2 c4g3 |
- c<n> significa cluster n.
- g<m significa glifo m> .
- u<p> significa punto di codice Unicode p.
- | 0 | 1 | 4 4 4 | 5 5 |
Requisiti
| Client minimo supportato | Windows Vista [solo app desktop] |
| Server minimo supportato | Windows Server 2008 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | usp10.h |
| Libreria | Usp10.lib |
| DLL | Usp10.dll |
| Componente ridistribuibile | Usp10.dll versione 1.600 o successiva in Windows XP |