Funzione ScriptShape (usp10.h)

Articolo
03/13/2024

Genera glifi e attributi visivi per un'esecuzione Unicode.

Sintassi

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

Parametri

[in] hdc

Facoltativo. 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] pwcChars

Puntatore a una matrice di caratteri Unicode che definiscono l'esecuzione.

[in] cChars

Numero di caratteri nell'esecuzione Unicode.

[in] cMaxGlyphs

Numero massimo di glifi da generare e lunghezza di pwOutGlyphs. Un valore ragionevole è (1.5 * cChars + 16), ma questo valore potrebbe essere insufficiente in alcune circostanze. Per altre informazioni, vedere la sezione Osservazioni.

[in, out] psa

Puntatore alla struttura SCRIPT_ANALYSIS per l'esecuzione, contenente i risultati di una chiamata precedente a ScriptItemize.

[out] pwOutGlyphs

Puntatore a un buffer in cui questa funzione recupera una matrice di glifi con dimensioni, come indicato da cMaxGlyphs.

[out] pwLogClust

Puntatore a un buffer in cui questa funzione recupera una matrice di informazioni sul cluster logico. Ogni elemento matrice corrisponde a un carattere nella matrice di caratteri Unicode; pertanto questa matrice ha il numero di elementi indicati da cChars. 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 è impostato su TRUE nella struttura SCRIPT_ANALYSIS , gli elementi diminuiscono man mano che la matrice viene letta.

[out] psva

Puntatore a un buffer in cui questa funzione recupera una matrice di strutture SCRIPT_VISATTR contenenti informazioni sugli attributi visivi. Poiché ogni glifo ha un solo attributo visivo, questa matrice ha il numero di elementi indicati 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 parametri 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 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 dall'esecuzione indicata da pwcChars. L'applicazione deve scegliere un altro tipo di carattere, usando ScriptGetCMap o un'altra funzione per selezionare il tipo di carattere.

Commenti

Per informazioni sul contesto in cui questa funzione viene normalmente chiamata, vedere Visualizzazione di testo con Uniscribe .

Se questa funzione restituisce E_OUTOFMEMORY, l'applicazione potrebbe chiamare ripetutamente ScriptShape , con buffer di output più grandi successivamente, fino a quando non viene fornito un buffer sufficientemente grande. Il numero di glifi generati da un punto di codice varia in base allo script e al tipo di carattere. Per uno script semplice, un punto di codice Unicode potrebbe generare un singolo glifo. Tuttavia, un tipo di carattere di script complesso potrebbe costruire caratteri dai componenti e quindi generare più volte il numero di glifi come caratteri. Esistono anche casi speciali, ad esempio rappresentazioni di caratteri non valide, in cui vengono aggiunti glifi aggiuntivi per rappresentare la sequenza non valida. Pertanto, un'ipotesi ragionevole per le dimensioni del buffer indicato da pwOutGlyphs è 1,5 volte la lunghezza del buffer di caratteri, più altri 16 glifi per rari casi, ad esempio, rappresentazione di sequenza non valida.

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 ScriptShape 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 , ScriptShape 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.

ScriptShape 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 ScriptItemize, per identificare la sequenziazione da sinistra a destra o da destra a sinistra.

Importante A partire da Windows 8: per mantenere la possibilità di eseguire in Windows 7, un modulo che usa Uniscribe deve specificare Usp10.lib prima di gdi32.lib nell'elenco di librerie.

Esempio

L'esempio seguente mostra come ScriptShape 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, dove c<n>u<m> significa cluster n, punto di codice Unicode m:

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

Matrice di glifi, dove c<n>g<m> significa cluster n, glifo m:

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

Matrice di cluster, ovvero l'offset (in glifi) nel cluster contenente il carattere :

| 0 | 1 | 4 4 4 | 5 5 |

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	usp10.h
Libreria	Usp10.lib
DLL	Usp10.dll