Compartilhar via


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.
Se essa função retornar E_OUTOFMEMORY, o aplicativo poderá chamar ScriptShapeOpenType 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 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.
Ilustração mostrando o intervalo, o item, a execução e o recurso de cada palavra em uma linha de texto que usa seis propriedades para apresentar oito palavras
Nota A ilustração usa muitas chamadas para ScriptShapeOpenType, cada uma representando uma execução.
 
Importante A partir do 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 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
A execução é descrita da seguinte maneira nas matrizes de caracteres e glifos.

Matriz de caracteres:

  • | c1u1 | c2u1 | c3u1 c3u2 c3u3 | c4u1 c4u2 |
Matriz de glifo:
  • | c1g1 | c2g1 c2g2 c2g3 | c3g1 | c4g1 c4g2 c4g3 |
A notação para os elementos da matriz consiste nesses itens:
  • c<n> significa cluster n.
  • g<m> significa glifo m.
  • u<p> significa ponto de código Unicode p.
A matriz de cluster gerada armazena deslocamentos para o cluster que contém o caractere . As unidades são expressas em glifos.
  • | 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

Confira também

Exibindo texto com Uniscribe

OPENTYPE_FEATURE_RECORD

SCRIPT_ANALYSIS

ScriptItemizeOpenType

ScriptPlaceOpenType

Scriptshape

Scripttextout

TEXTRANGE_PROPERTIES

Funções Uniscribe