ScriptItemizeOpenType 함수(usp10.h)

아티클
08/26/2023

유니코드 문자열을 개별적으로 셰이프 가능한 항목 으로 분할하고 OpenType 처리를 위해 각 셰이프 가능한 항목에 대한 기능 태그 배열을 제공합니다.

구문

HRESULT ScriptItemizeOpenType(
  [in]           const WCHAR          *pwcInChars,
  [in]           int                  cInChars,
  [in]           int                  cMaxItems,
  [in, optional] const SCRIPT_CONTROL *psControl,
  [in, optional] const SCRIPT_STATE   *psState,
  [out]          SCRIPT_ITEM          *pItems,
  [out]          OPENTYPE_TAG         *pScriptTags,
  [out]          int                  *pcItems
);

매개 변수

[in] pwcInChars

항목화할 유니코드 문자열에 대한 포인터입니다.

[in] cInChars

항목별로 지정할 pwcInChars의 문자 수입니다.

[in] cMaxItems

처리할 항목을 정의하는 최대 SCRIPT_ITEM 구조체 수입니다.

[in, optional] psControl

수행할 항목화 유형을 나타내는 SCRIPT_CONTROL 구조체에 대한 포인터입니다.

또는 SCRIPT_CONTROL 속성이 필요하지 않은 경우 애플리케이션에서 이 매개 변수를 NULL로 설정할 수 있습니다. 자세한 내용은 주의 섹션을 참조하세요.

[in, optional] psState

초기 양방향 알고리즘 상태를 나타내는 SCRIPT_STATE 구조체에 대한 포인터입니다.

또는 스크립트 상태가 필요하지 않은 경우 애플리케이션에서 이 매개 변수를 NULL 로 설정할 수 있습니다. 자세한 내용은 주의 섹션을 참조하세요.

[out] pItems

함수가 처리된 항목을 나타내는 SCRIPT_ITEM 구조를 검색하는 버퍼에 대한 포인터입니다. 버퍼의 길이는 바이트여야 (cMaxItems + 1) * sizeof(SCRIPT_ITEM) 합니다. 두 개 미만의 SCRIPT_ITEM 구조를 처리하는 버퍼를 사용하여 이 함수를 호출하는 것은 잘못되었습니다. 함수는 항상 항목 분석 배열에 터미널 항목을 추가하여 0부터 시작하는 인덱스 "i"가 있는 항목의 길이를 항상 다음과 같이 사용할 수 있도록 합니다.

pItems[i+1].iCharPos - pItems[i].iCharPos;

[out] pScriptTags

함수가 스크립트 태그를 나타내는 OPENTYPE_TAG 구조체의 배열을 검색하는 버퍼에 대한 포인터입니다. 버퍼의 길이는 바이트여야 cMaxItems * sizeof(OPENTYPE_TAG) 합니다.

참고 항목의 모든 문자가 중립인 경우 이 매개 변수의 값은 SCRIPT_TAG_UNKNOWN(0x00000000)입니다. 예를 들어 항목이 문장 부호로 완전히 구성된 경우 이러한 문제가 발생할 수 있습니다.

[out] pcItems

처리된 SCRIPT_ITEM 구조체 수에 대한 포인터입니다.

반환 값

정상적으로 실행되는 경우 0을 반환합니다. 함수가 성공하지 못하면 0이 아닌 HRESULT 값을 반환합니다. 모든 오류 사례에서 항목이 완전히 처리되지 않고 출력의 일부에 정의된 값이 포함되지 않습니다. 애플리케이션은 SUCCEEDED 및 FAILED 매크로를 사용하여 반환 값을 테스트 할 수 있습니다.

cMaxItems로 표시된 크기가 너무 작으면 함수는 E_OUTOFMEMORY 반환합니다. 애플리케이션은 더 큰 버퍼를 사용하여 함수를 다시 호출할 수 있습니다.

함수는 다음 조건 중 하나 이상이 발생하는 경우 E_INVALIDARG 반환합니다.

pwcInChars가 NULL로 설정됩니다.
cInChars는 0입니다.
pItems가 NULL로 설정됩니다.
pScriptTags가 NULL로 설정됩니다.
cMaxItems< 2

설명

ScriptItemizeOpenType 은 이전 ScriptItemize 함수보다 선호됩니다. ScriptItemizeOpenType의 장점 중 하나는 각 셰이핑 가능한 항목에 대한 기능 태그의 가용성입니다.

이 함수가 일반적으로 호출되는 컨텍스트에 대한 설명은 유니스크립을 사용하여 텍스트 표시 를 참조하세요.

함수는 셰이핑 엔진의 변경 또는 방향 변경으로 항목을 구분합니다.

애플리케이션은 ScriptItemizeOpenType에서 검색된 각 SCRIPT_ITEM 구조에서 단일 항목 내에 완전히 속하는 여러 범위를 만들거나 실행할 수 있습니다. 그러나 여러 항목을 단일 실행으로 결합하면 안 됩니다. 측정하거나 렌더링할 때 애플리케이션은 각 실행에 대해 ScriptShapeOpenType을 호출할 수 있으며 ScriptItemizeOpenType에서 검색한 SCRIPT_ITEM 구조체에서 해당 SCRIPT_ANALYSIS 구조를 전달해야 합니다.

애플리케이션에서 처리하는 텍스트에 오른쪽에서 왼쪽 콘텐츠가 포함될 수 있는 경우 애플리케이션은 ScriptItemizeOpenType을 호출할 때 psControl 및 psState 매개 변수를 사용합니다. 그러나 애플리케이션은 이 작업을 수행할 필요가 없으며 Uniscribe를 사용하는 대신 양방향 텍스트 자체를 처리할 수 있습니다. psControl 및 psState 매개 변수는 SCRIPT_CONTROL fLinkStringBefore 멤버가 오른쪽에서 왼쪽 스크립트와 관련이 없는 경우와 같이 일부 엄격하게 왼쪽에서 오른쪽 시나리오에서 유용합니다. 애플리케이션은 psControl 및 psState 를 NULL 로 설정하여 ScriptItemizeOpenType 이 유니코드 문자열을 문자 코드로만 중단하도록 합니다.

애플리케이션은 모든 매개 변수를 NULL 이 아닌 값으로 설정하여 함수가 전체 유니코드 양방향 분석을 수행하도록 할 수 있습니다. 올바른 유니코드 양방향 분석을 허용하려면 단락 시작 시 읽기 순서에 따라 SCRIPT_STATE 구조를 초기화하고 ScriptItemizeOpenType 을 전체 단락에 전달해야 합니다. 특히 uBidiLevel 멤버는 왼쪽에서 오른쪽으로 0으로, 오른쪽에서 왼쪽으로 1로 초기화해야 합니다.

SCRIPT_ANALYSISfRTL 멤버는 SCRIPT_ITEM 참조됩니다. SCRIPT_PROPERTIESfNumeric 멤버는 ScriptGetProperties에 의해 검색됩니다. 이러한 멤버는 GetCharacterPlacement의 lpResults에서 참조하는 GCP_RESULTSlpClass 멤버와 동일한 분류를 제공합니다.

다음 표와 같이 유럽 숫자 U+0030~U+0039를 국가 숫자로 렌더링할 수 있습니다.

SCRIPT_STATE.fDigitSubstitute	SCRIPT_CONTROL.fContextDigits	유니코드 U+0030~U+0039에 대해 표시되는 숫자 셰이프
FALSE	모두	유럽 숫자
TRUE	FALSE	SCRIPT_CONTROL uDefaultLanguage 멤버에 지정된 대로
TRUE	TRUE	이전의 강력한 텍스트로, 기본값은 SCRIPT_CONTROL uDefaultLanguage 멤버입니다.

컨텍스트 숫자 모드에서 다음 작업 중 하나가 발생합니다.

uDefaultLanguage에서 지정한 스크립트가 출력과 동일한 방향이면 첫 번째 문자 이전에 발생한 모든 숫자가 uDefaultLanguage로 표시된 언어로 렌더링됩니다.
uDefaultLanguage로 지정된 스크립트가 출력과 반대 방향이면 첫 번째 문자가 유럽 숫자로 렌더링되기 전에 발생한 모든 숫자가 렌더링됩니다.

예를 들어 uDefaultLanguage 가 LANG_ARABIC 나타내는 경우 초기 숫자는 오른쪽에서 왼쪽 포함에 Arabic-Indic 있습니다. 그러나 왼쪽에서 오른쪽 포함의 유럽 숫자입니다.

자세한 내용은 숫자 셰이프를 참조하세요.

유니코드 컨트롤 문자와 정의 및 SCRIPT_STATE 멤버에 미치는 영향은 다음 표에 나와 있습니다. 유니코드 컨트롤 문자에 대한 자세한 내용은 유니코드 표준을 참조하세요.

유니코드 컨트롤 문자	의미	SCRIPT_STATE 영향
NADS	국가별 숫자 셰이프를 사용하여 NODS(유럽 숫자)를 재정의합니다.	fDigitSubstitute를 설정합니다.
끄 덕	명목 숫자 셰이프(유럽 숫자라고도 함)를 사용합니다. NADS를 참조하세요.	fDigitSubstitute를 지웁니다.
엉덩이	대칭 쌍(예: 괄호)의 교환을 활성화합니다. 이러한 문자의 경우 왼쪽과 오른쪽은 여는 것과 닫는 것으로 해석됩니다. 이것이 기본값입니다. ISS를 참조하세요.	fInhibitSymSwap을 지웁니다.
ISS	대칭 쌍의 교환을 금지합니다. ASS를 참조하세요.	fInhibitSymSwap을 설정합니다.
AAFS	아랍어 프레젠테이션 양식에 대한 아랍어 양식 셰이핑을 활성화합니다. IAFS를 참조하세요.	fCharShape를 설정합니다.
IAFS	아랍어 프레젠테이션 양식의 경우 아랍어 양식 셰이핑, 즉 합자 및 필기체 연결을 억제합니다. 명목 아랍어 문자는 영향을 받지 않습니다. 이것이 기본값입니다. AAFS를 참조하세요.	fCharShape를 지웁다.

SCRIPT_STATEfArabicNumContext 멤버는 아랍어 스크립트 텍스트에서 상황에 맞는 숫자 표시를 지원합니다. 네이티브 아랍어 스크립트 숫자 셰이프 또는 유럽 숫자를 사용하여 숫자가 렌더링되는지 여부를 나타냅니다. 단락의 시작 부분에서 이 멤버는 일반적으로 아랍어 로캘의 경우 TRUE 로 초기화되고 다른 로캘의 경우 FALSE 로 초기화되어야 합니다. 함수는 강력한 텍스트를 처리할 때 스크립트 상태를 업데이트합니다.

출력 매개 변수 pScriptTags 는 항목과 평행한 항목이 있는 배열을 나타냅니다. 각 항목에 대해 이 함수는 모든 후속 작업에서 셰이핑에 사용해야 하는 스크립트 태그를 검색합니다.

스크립트 태그는 일반적으로 입력 문자의 ScriptItemizeOpenType 에 의해 결정됩니다. 함수가 특정 스크립트 태그를 검색하는 경우 애플리케이션은 변경하지 않고 다른 함수에 전달해야 합니다. 그러나 문자가 중립(예: 숫자)이고 스크립트를 확인할 수 없는 경우 애플리케이션은 텍스트와 연결된 글꼴 및 언어에 따라 적절한 스크립트 태그를 선택해야 합니다.

중요 Windows 8 시작: Windows 7에서 실행하는 기능을 유지하려면 Uniscribe를 사용하는 모듈이 라이브러리 목록에서 gdi32.lib 전에 Usp10.lib를 지정해야 합니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	usp10.h
라이브러리	Usp10.lib
DLL	Usp10.dll
재배포 가능 파일	Windows XP에서 Usp10.dll 버전 1.600 이상