Función ScriptShape (usp10.h)

Artículo
03/08/2023

Genera glifos y atributos visuales para una ejecución Unicode.

Sintaxis

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 del contexto del dispositivo. Para obtener más información, consulte Almacenamiento en caché.

[in, out] psc

Puntero a una estructura de SCRIPT_CACHE que identifica la caché de scripts.

[in] pwcChars

Puntero a una matriz de caracteres Unicode que definen la ejecución.

[in] cChars

Número de caracteres de la ejecución Unicode.

[in] cMaxGlyphs

Número máximo de glifos que se van a generar y la longitud de pwOutGlyphs. Un valor razonable es (1.5 * cChars + 16), pero este valor podría ser insuficiente en algunas circunstancias. Para obtener más información, vea la sección Comentarios.

[in, out] psa

Puntero a la estructura SCRIPT_ANALYSIS de la ejecución, que contiene los resultados de una llamada anterior a ScriptItemize.

[out] pwOutGlyphs

Puntero a un búfer en el que esta función recupera una matriz de glifos con tamaño, como se indica en cMaxGlyphs.

[out] pwLogClust

Puntero a un búfer en el que esta función recupera una matriz de información del clúster lógico. Cada elemento de matriz corresponde a un carácter de la matriz de caracteres Unicode; por lo tanto, esta matriz tiene el número de elementos indicados por cChars. El valor de cada elemento es el desplazamiento del primer glifo de la ejecución al primer glifo del clúster que contiene el carácter correspondiente. Tenga en cuenta que, cuando el miembro fRTL se establece en TRUE en la estructura SCRIPT_ANALYSIS , los elementos disminuyen a medida que se lee la matriz.

[out] psva

Puntero a un búfer en el que esta función recupera una matriz de SCRIPT_VISATTR estructuras que contienen información de atributo visual. Dado que cada glifo tiene solo un atributo visual, esta matriz tiene el número de elementos indicados por cMaxGlyphs.

[out] pcGlyphs

Puntero a la ubicación en la que esta función recupera el número de glifos indicados en pwOutGlyphs.

Valor devuelto

Si la operación se realiza correctamente, devuelve 0. La función devuelve un valor HRESULT distinto de cero si no se realiza correctamente. En todos los casos de error, el contenido de todos los parámetros de salida no está definido.

Entre las devoluciones de error se incluyen:

E_OUTOFMEMORY. La longitud del búfer de salida indicada por cMaxGlyphs no es suficiente.
E_PENDING. La caché de scripts especificada por el parámetro psc no contiene suficiente información para dar forma a la cadena y el contexto del dispositivo se ha pasado como NULL para que la función no pueda completar el proceso de forma. La aplicación debe configurar un contexto de dispositivo correcto para la ejecución y llamar a esta función de nuevo con el valor adecuado en hdc y con todos los demás parámetros iguales.
USP_E_SCRIPT_NOT_IN_FONT. La fuente correspondiente al contexto del dispositivo no admite el script requerido por la ejecución indicada por pwcChars. La aplicación debe elegir otra fuente, mediante ScriptGetCMap u otra función para seleccionar la fuente.

Comentarios

Vea Mostrar texto con Uniscribe para obtener una explicación del contexto en el que normalmente se llama a esta función.

Si esta función devuelve E_OUTOFMEMORY, la aplicación podría llamar a ScriptShape repetidamente, con búferes de salida sucesivamente más grandes, hasta que se proporcione un búfer lo suficientemente grande. El número de glifos generados por un punto de código varía según el script y la fuente. Para un script simple, un punto de código Unicode podría generar un único glifo. Sin embargo, una fuente de script compleja podría construir caracteres a partir de componentes y, por tanto, generar varios glifos como caracteres. Además, hay casos especiales, como representaciones de caracteres no válidas, en los que se agregan glifos adicionales para representar la secuencia no válida. Por lo tanto, una estimación razonable para el tamaño del búfer indicado por pwOutGlyphs es de 1,5 veces la longitud del búfer de caracteres, además de 16 glifos adicionales para casos poco frecuentes, por ejemplo, representación de secuencia no válida.

Esta función puede establecer el miembro fNoGlyphIndex de la estructura SCRIPT_ANALYSIS si la fuente o el sistema operativo no pueden admitir índices de glifo.

La aplicación puede llamar a ScriptShape para determinar si una fuente admite los caracteres de una cadena determinada. Si la función devuelve S_OK, la aplicación debe comprobar la salida de los glifos que faltan. Si fLogicalOrder se establece en TRUE en la estructura SCRIPT_ANALYSIS , la función siempre genera glifos en el mismo orden que los caracteres Unicode originales. Si fLogicalOrder se establece en FALSE, la función genera elementos de derecha a izquierda en orden inverso para que ScriptTextOut no tenga que invertirlos antes de llamar a ExtTextOut.

Si el miembro eScript de SCRIPT_ANALYSIS se establece en SCRIPT_UNDEFINED, se deshabilita la forma. En este caso, ScriptShape muestra el glifo que se encuentra en la tabla cmap de fuente. Si no hay glifo en la tabla, la función indica que faltan glifos.

ScriptShape secuencia clústeres uniformemente dentro de la ejecución y secuencias glifos uniformemente dentro de un clúster. Usa el valor del miembro fRTL de SCRIPT_ANALYSIS, de ScriptItemize, para identificar la secuenciación como de izquierda a derecha o de derecha a izquierda.

Importante A partir de Windows 8: para mantener la capacidad de ejecutarse en Windows 7, un módulo que usa Uniscribe debe especificar Usp10.lib antes de gdi32.lib en su lista de bibliotecas.

Ejemplos

En el ejemplo siguiente se muestra cómo ScriptShape genera una matriz de clúster lógico (pwLogClust) a partir de una matriz de caracteres (pwcChars) y una matriz de glifos (pwOutGlyphs). La ejecución tiene cuatro clústeres.

Primer clúster: un carácter representado por un glifo
Segundo clúster: un carácter representado por tres glifos
Tercer clúster: tres caracteres representados por un glifo
Cuarto clúster: dos caracteres representados por tres glifos

Matriz de caracteres, donde c<n>u<m> significa clúster n, punto de código Unicode m:

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

La matriz de glifos, donde c<n>g<m> significa el clúster n, glifo m:

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

Matriz de clúster, es decir, el desplazamiento (en glifos) al clúster que contiene el carácter:

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

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	usp10.h
Library	Usp10.lib
Archivo DLL	Usp10.dll