Função ScriptShapeOpenType (usp10.h)
Gera glifos e atributos visuais para uma execução Unicode com informações de OpenType. Cada execução consiste em uma chamada para essa função.
Sintaxe
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
);
Parâmetros
[in, optional] hdc
Identificador para o contexto do dispositivo. Para obter mais informações, consulte Cache.
[in, out] psc
Ponteiro para uma estrutura SCRIPT_CACHE que identifica o cache de script.
[in, out] psa
Ponteiro para uma estrutura SCRIPT_ANALYSIS obtida de uma chamada anterior para ScriptItemizeOpenType. A estrutura identifica o mecanismo de formatação para que os glifos possam ser formados corretamente.
Como alternativa, o aplicativo pode definir esse parâmetro como NULL para receber resultados não filtrados.
[in] tagScript
Uma estrutura OPENTYPE_TAG que define a marca de script OpenType para o sistema de escrita.
[in] tagLangSys
Uma estrutura OPENTYPE_TAG que contém a marca de idioma OpenType para o sistema de escrita.
[in, optional] rcRangeChars
Matriz de caracteres em cada intervalo. O número de elementos de matriz é indicado por cRanges. Os valores dos elementos dessa matriz somam-se ao valor de cChars.
[in, optional] rpRangeProperties
Matriz de estruturas TEXTRANGE_PROPERTIES , cada uma representando um intervalo de recursos OpenType. O número de estruturas é indicado pelo parâmetro cRanges . Para obter mais informações sobre rpRangeProperties, consulte a seção Comentários.
[in] cRanges
O número de intervalos de recursos OpenType.
[in] pwcChars
Ponteiro para uma matriz de caracteres Unicode que contém a execução.
[in] cChars
Número de caracteres na execução Unicode.
[in] cMaxGlyphs
Número máximo de glifos a serem gerados.
[out] pwLogClust
Ponteiro para um buffer no qual essa função recupera uma matriz de informações de cluster lógico. Cada elemento de matriz corresponde a um caractere na matriz de caracteres Unicode. O valor de cada elemento é o deslocamento do primeiro glifo na execução para o primeiro glifo no cluster que contém o caractere correspondente. Observe que, quando o membro fRTL da estrutura SCRIPT_ANALYSIS é TRUE, os elementos diminuem à medida que a matriz é lida.
[out] pCharProps
Ponteiro para um buffer no qual essa função recupera uma matriz de valores de propriedade de caractere, de comprimento indicado por cChars.
[out] pwOutGlyphs
Ponteiro para um buffer no qual essa função recupera uma matriz de glifos.
[out] pOutGlyphProps
Ponteiro para um buffer no qual essa função recupera uma matriz de atributos para cada um dos glifos recuperados. O comprimento dos valores é igual ao valor de pcGlyphs. Como uma propriedade de glifo é indicada por glifo, o valor desse parâmetro indica o número de elementos especificados por cMaxGlyphs.
[out] pcGlyphs
Ponteiro para o local em que essa função recupera o número de glifos indicados em pwOutGlyphs.
Valor retornado
Retorna 0 se for bem-sucedido. A função retornará um valor HRESULT diferente de zero se não for bem-sucedida. Em todos os casos de erro, o conteúdo de todos os valores de matriz de saída é indefinido.
Os retornos de erro incluem:
- E_OUTOFMEMORY. O comprimento do buffer de saída indicado por cMaxGlyphs é insuficiente.
- E_PENDING. O cache de script especificado pelo parâmetro psc não contém informações suficientes para moldar a cadeia de caracteres e o contexto do dispositivo foi passado como NULL para que a função não possa concluir o processo de formatação. O aplicativo deve configurar um contexto de dispositivo correto para a execução e chamar essa função novamente com o valor de contexto apropriado em hdc e com todos os outros parâmetros da mesma forma.
- USP_E_SCRIPT_NOT_IN_FONT. A fonte correspondente ao contexto do dispositivo não dá suporte ao script necessário. O aplicativo deve escolher outra fonte, usando ScriptGetCMap ou outro método para selecionar a fonte.
Comentários
ScriptShapeOpenType é preferencial em relação à função ScriptShape mais antiga. Algumas vantagens do ScriptShapeOpenType incluem o seguinte:
- Os parâmetros correspondem diretamente às marcas OpenType em tabelas de layout de fonte.
- Os parâmetros definem os recursos aplicados a cada caractere.
- A entrada é dividida em execuções. Cada execução tem propriedades OpenType e consiste em uma única chamada para ScriptShapeOpenType.
Essa função pode definir o membro fNoGlyphIndex da estrutura SCRIPT_ANALYSIS se a fonte ou o sistema operacional não puder dar suporte a índices de glifo.
O aplicativo pode chamar ScriptShapeOpenType para determinar se uma fonte dá suporte aos caracteres em uma determinada cadeia de caracteres. Se a função retornar S_OK, o aplicativo deverá marcar a saída para glifos ausentes. Se fLogicalOrder for definido como TRUE na estrutura SCRIPT_ANALYSIS , a função sempre gerará glifos na mesma ordem que os caracteres Unicode originais. Se fLogicalOrder for definido como FALSE, a função gerará itens da direita para a esquerda na ordem inversa para que ScriptTextOut não precise revertê-los antes de chamar ExtTextOut.
Se o membro eScript do SCRIPT_ANALYSIS estiver definido como SCRIPT_UNDEFINED, a formatação será desabilitada. Nesse caso, ScriptShapeOpenType exibe o glifo que está na tabela cmap de fonte. Se nenhum glifo estiver na tabela, a função indicará que os glifos estão ausentes.
ScriptShapeOpenType sequencia clusters uniformemente dentro da execução e sequencia glifos uniformemente dentro de um cluster. Ele usa o valor do membro fRTL de SCRIPT_ANALYSIS, de ScriptItemizeOpenType, para identificar se o sequenciamento é da esquerda para a direita ou da direita para a esquerda.
Para o parâmetro rpRangeProperties , a estrutura TEXTRANGE_PROPERTIES aponta para uma matriz de estruturas OPENTYPE_FEATURE_RECORD . Essa matriz é usada da seguinte maneira:
- Cada elemento da matriz indicada para rpRangeProperties descreve um intervalo.
- Intervalos de propriedades específicas de compartilhamento de texto tendem a "aninhar", e intervalos aninhados podem compartilhar OPENTYPE_FEATURE_RECORD informações. Por exemplo, na ilustração abaixo:
- As linhas de números na parte superior representam intervalos, itens e execuções, respectivamente.
- Cada intervalo rotulado aqui com uma letra representa um único recurso OpenType. Os recursos que se enquadram em cada intervalo são armazenados na matriz OPENTYPE_FEATURE_RECORD desse intervalo.
- Para cada intervalo, a matriz de estruturas OPENTYPE_FEATURE_RECORD corresponde às letras dos intervalos que contêm esse intervalo.
- Nesta ilustração, o intervalo 2 está indiretamente associado às estruturas de OPENTYPE_FEATURE_RECORD para os intervalos A, B e C. O intervalo 4 está associado apenas às estruturas dos intervalos A e D.
Exemplos
O exemplo a seguir mostra como ScriptShapeOpenType gera uma matriz de cluster lógico (pwLogClust) de uma matriz de caracteres (pwcChars) e uma matriz de glifo (pwOutGlyphs). A execução tem quatro clusters.
- Primeiro cluster: um caractere representado por um glifo
- Segundo cluster: um caractere representado por três glifos
- Terceiro cluster: três caracteres representados por um glifo
- Quarto cluster: dois caracteres representados por três glifos
Matriz de caracteres:
- | 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 ponto de código Unicode p.
- | 0 | 1 | 4 4 4 | 5 5 |
Requisitos
| Cliente mínimo com suporte | Windows Vista [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2008 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | usp10.h |
| Biblioteca | Usp10.lib |
| DLL | Usp10.dll |
| Redistribuível | Usp10.dll versão 1.600 ou superior no Windows XP |