Функция ScriptShape (usp10.h)

Статья
08/26/2023

Создает глифы и визуальные атрибуты для выполнения Юникода.

Синтаксис

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

Параметры

[in] hdc

Необязательный параметр. Обработка в контексте устройства. Дополнительные сведения см. в разделе Кэширование.

[in, out] psc

Указатель на структуру SCRIPT_CACHE , определяющую кэш скриптов.

[in] pwcChars

Указатель на массив символов Юникода, определяющих выполнение.

[in] cChars

Количество символов в выполнении Юникода.

[in] cMaxGlyphs

Максимальное число глифов для создания и длина pwOutGlyphs. Разумное значение — (1.5 * cChars + 16), но в некоторых случаях это значение может оказаться недостаточным. Дополнительные сведения см. в разделе «Примечания».

[in, out] psa

Указатель на структуру SCRIPT_ANALYSIS для выполнения, содержащую результаты предыдущего вызова ScriptItemize.

[out] pwOutGlyphs

Указатель на буфер, в котором эта функция извлекает массив глифов с размером, указанным cMaxGlyphs.

[out] pwLogClust

Указатель на буфер, в котором эта функция извлекает массив сведений о логическом кластере. Каждый элемент массива соответствует символу в массиве символов Юникода; поэтому этот массив содержит количество элементов, указанных cChars. Значение каждого элемента — это смещение от первого глифа в выполнении до первого глифа в кластере, содержающем соответствующий символ. Обратите внимание, что, когда член fRTL имеет значение TRUE в структуре SCRIPT_ANALYSIS , элементы уменьшаются по мере считывания массива.

[out] psva

Указатель на буфер, в котором эта функция извлекает массив SCRIPT_VISATTR структур, содержащих сведения о визуальных атрибутах. Так как каждый глиф имеет только один визуальный атрибут, этот массив содержит количество элементов, указанных cMaxGlyphs.

[out] pcGlyphs

Указатель на расположение, в котором эта функция извлекает количество глифов, указанных в pwOutGlyphs.

Возвращаемое значение

Возвращает 0 в случае успеха. Функция возвращает ненулевое значение HRESULT, если это не удалось. Во всех случаях ошибок содержимое всех выходных параметров не определено.

Возвращается ошибка:

E_OUTOFMEMORY. Длина выходного буфера, указанная cMaxGlyphs , недостаточна.
E_PENDING. Кэш скриптов, заданный параметром psc , не содержит достаточно сведений для формирования строки, а контекст устройства был передан как NULL , поэтому функция не может завершить процесс формирования. Приложение должно настроить правильный контекст устройства для запуска и снова вызвать эту функцию с соответствующим значением в hdc и с теми же параметрами.
USP_E_SCRIPT_NOT_IN_FONT. Шрифт, соответствующий контексту устройства, не поддерживает скрипт, необходимый для выполнения, указанного pwcChars. Приложение должно выбрать другой шрифт, используя ScriptGetCMap или другую функцию для выбора шрифта.

Если эта функция возвращает E_OUTOFMEMORY, приложение может многократно вызывать ScriptShape с последовательно большими выходными буферами, пока не будет предоставлен достаточно большой буфер. Количество глифов, созданных кодовой точкой, зависит от скрипта и шрифта. Для простого скрипта кодовая точка Юникода может создать один глиф. Однако сложный шрифт скрипта может создавать символы из компонентов и таким образом генерировать в несколько раз больше глифов, чем символов. Кроме того, существуют особые случаи, например недопустимые представления символов, в которых добавляются дополнительные глифы для представления недопустимой последовательности. Таким образом, разумное предположение для размера буфера, указанного pwOutGlyphs , в 1,5 раза больше длины буфера символов, а также дополнительные 16 глифов в редких случаях, например недопустимое представление последовательности.

Эта функция может задать элемент fNoGlyphIndexструктуры SCRIPT_ANALYSIS , если шрифт или операционная система не поддерживают индексы глифов.

Приложение может вызвать ScriptShape , чтобы определить, поддерживает ли шрифт символы в заданной строке. Если функция возвращает S_OK, приложение должно проверка выходные данные отсутствующих глифов. Если fLogicalOrder имеет значение TRUE в структуре SCRIPT_ANALYSIS , функция всегда создает глифы в том же порядке, что и исходные символы Юникода. Если параметр fLogicalOrder имеет значение FALSE, функция создает элементы справа налево в обратном порядке, чтобы scriptTextOut не нужно было их отменять перед вызовом ExtTextOut.

Если для элемента eScriptSCRIPT_ANALYSIS задано значение SCRIPT_UNDEFINED, формирование отключается. В этом случае ScriptShape отображает глиф, который находится в таблице cmap шрифтов. Если в таблице нет глифа, функция указывает, что глифы отсутствуют.

ScriptShape последовательности кластеров равномерно в пределах выполнения и последовательности глифов в кластере. Для определения последовательности слева направо или справа налево используется значение элемента fRTLSCRIPT_ANALYSIS из ScriptItemize.

Важно Начиная с Windows 8. Чтобы поддерживать возможность запуска в Windows 7, модуль, использующий Uniscribe, должен указать Usp10.lib перед gdi32.lib в списке библиотек.

Примеры

В следующем примере показано, как ScriptShape создает массив логического кластера (pwLogClust) из массива символов (pwcChars) и массива глифов (pwOutGlyphs). Запуск состоит из четырех кластеров.

Первый кластер: один символ, представленный одним глифом
Второй кластер: один символ, представленный тремя глифами
Третий кластер: три символа, представленные одним глифом
Четвертый кластер: два символа, представленные тремя глифами

Массив символов, где c<n>u<m> означает кластер n, кодовая точка Юникода m:

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

Массив глифов, где c<n>g<m> означает кластер n, глиф m:

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

Массив кластера, то есть смещение (в глифах) до кластера, содержащего символ:

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

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	usp10.h
Библиотека	Usp10.lib
DLL	Usp10.dll