Função ScriptShape (usp10.h)

Gera glifos e atributos visuais para uma execução Unicode.

Sintaxe

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

Parâmetros

[in] hdc

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

Ponteiro para uma matriz de caracteres Unicode que define a execução.

[in] cChars

Número de caracteres na execução Unicode.

[in] cMaxGlyphs

Número máximo de glifos a serem gerados e o comprimento de pwOutGlyphs. Um valor razoável é (1.5 * cChars + 16), mas esse valor pode ser insuficiente em algumas circunstâncias. Para obter mais informações, consulte a seção Comentários.

[in, out] psa

Ponteiro para a estrutura de SCRIPT_ANALYSIS para a execução, contendo os resultados de uma chamada anterior para ScriptItemize.

[out] pwOutGlyphs

Ponteiro para um buffer no qual essa função recupera uma matriz de glifos com tamanho, conforme indicado por cMaxGlyphs.

[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; portanto, essa matriz tem o número de elementos indicados por cChars. 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 é definido como TRUE na estrutura SCRIPT_ANALYSIS , os elementos diminuem à medida que a matriz é lida.

[out] psva

Ponteiro para um buffer no qual essa função recupera uma matriz de estruturas SCRIPT_VISATTR que contêm informações de atributo visual. Como cada glifo tem apenas um atributo visual, essa matriz tem o número de elementos indicados por cMaxGlyphs.

[out] pcGlyphs

Ponteiro para o local em que essa função recupera o número de glifos indicados em pwOutGlyphs.

Retornar valor

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 parâmetros 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 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 exigido pela execução indicada por pwcChars. O aplicativo deve escolher outra fonte, usando ScriptGetCMap ou outra função para selecionar a fonte.

Comentários

Consulte Exibindo texto com Uniscribe para ver uma discussão sobre o contexto no qual essa função normalmente é chamada.

Se essa função retornar E_OUTOFMEMORY, o aplicativo poderá chamar ScriptShape repetidamente, com buffers de saída sucessivamente maiores, até que um buffer grande o suficiente seja fornecido. O número de glifos gerados por um ponto de código varia de acordo com o script e a fonte. Para um script simples, um ponto de código Unicode pode gerar um único glifo. No entanto, uma fonte de script complexa pode construir caracteres de componentes e, portanto, gerar várias vezes mais glifos do que caracteres. Além disso, há casos especiais, como representações de caractere inválidas, em que glifos extras são adicionados para representar a sequência inválida. Portanto, uma estimativa razoável para o tamanho do buffer indicado por pwOutGlyphs é 1,5 vezes o comprimento do buffer de caracteres, além de 16 glifos adicionais para casos raros, por exemplo, representação de sequência inválida.

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

O ScriptShape 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 ScriptItemize, para identificar o sequenciamento como da esquerda para a direita ou da direita para a esquerda.

Importante Começando com Windows 8: para manter a capacidade de execução no Windows 7, um módulo que usa Uniscribe deve especificar Usp10.lib antes de gdi32.lib em sua lista de bibliotecas.
 

Exemplos

O exemplo a seguir mostra como ScriptShape 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, em que c<n>u<m> significa cluster n, ponto de código Unicode m:
  • | c1u1 | c2u1 | c3u1 c3u2 c3u3 | c4u1 c4u2 |
Matriz de glifo, em que c<n>g<m> significa cluster n, glifo m:
  • | c1g1 | c2g1 c2g2 c2g3 | c3g1 | c4g1 c4g2 c4g3 |
Matriz de cluster, ou seja, o deslocamento (em glifos) para o cluster que contém o caractere:
  • | 0 | 1 | 4 4 4 | 5 5 |

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho usp10.h
Biblioteca Usp10.lib
DLL Usp10.dll

Confira também

Exibindo texto com Uniscribe

SCRIPT_ANALYSIS

SCRIPT_CACHE

SCRIPT_VISATTR

Scriptitemize

ScriptShapeOpenType

Scripttextout

Uniscribe

Funções Uniscribe