Microsoft 게임 개발 키트의 UTF-8 지원
이 항목에서는 Microsoft GDK(게임 개발 키트)에서 UTF-8 지원에 대한 개요를 제공합니다.
- 개요
- --A 대 -W API
- 본체 코드 페이지
- Windows PC 코드 페이지
- MultiByteToWideChar/WideCharToMultiByte
- 고급 UTF-8에 대한 ICU 및 세계화 지원
- 이전 버전의 Windows 지원
개요
UTF-8은 국제화 유니버설 코드 페이지이며 1–4바이트 가변 너비 인코딩을 사용하여 모든 유니코드 코드 포인트를 지원합니다. 웹에서 널리 사용되며, Unix 기반 시스템과 같은 경쟁 플랫폼은 기본적으로 UTF-8에서 작동합니다. UTF-8에서 작동 시 노력 및 테스트 부담을 최소화하고 국제 시나리오 및 데이터 교환을 최대화해야 합니다.
Windows는 기본적으로 UTF-16(또는 WCHAR)에서 작동하며, MultiByteToWideChar 및 WideCharToMultiByte을(를) 사용한 코드 페이지 변환이 필요합니다. 이것은 Windows가 여러 플랫폼을 대상으로 하는 코드에 부여하는 고유한 부담입니다. 훨씬 더 어려운 것은 지역 및 사용자 구성에 따라 다를 수 있고 잘못 의존할 때 완전히 일관되지 않은 동작이 발생할 수 있는 ANSI 코드 페이지의 Windows 개념입니다.
Microsoft GDK(게임 개발 키트) 및 Windows는 일반적으로 UTF-8을 지원하여 코드 대상 지정 또는 여러 플랫폼 및 웹과의 상호 교환에서 Windows의 고유한 부담을 없애기 위해 계속 지원하고 있습니다. 또한 그 결과 앱과 게임에서 국제화 문제가 더 적어지고 올바른 지원에 필요한 테스트 매트릭스가 축소됩니다.
-A 대 -W API
Win32 API는 종종 -A 및 -W 변형을 제공합니다.
-A 변형은 시스템에서 구성된 ANSI 코드 페이지를 존중하고 char*를 처리합니다.
-W 변형은 UTF-16에서 작동하고 WCHAR를 처리합니다.
최근까지 -A API는 Windows가 수십 년 동안 "유니코드" -W 변형을 권고하고 있었기 때문에 레거시로 간주되었습니다. 그러나 최근 릴리스에서 Windows는 ANSI 코드 페이지 및 -A API를 사용하여 최신 SKU에서 UTF-8 지원을 도입했습니다. ANSI 코드 페이지가 UTF-8로 구성된 경우 -API는 UTF-8에서 작동합니다. 이 모델은 어떠한 코드 변경 없이 -A API로 빌드된 기존 코드를 지원한다는 이점이 있습니다.
Microsoft GDK(게임 개발 키트)를 사용하는 경우 UTF-8은 기본값으로서 콘솔에서 유일한 ANSI 코드 페이지입니다. 콘솔의 -A API는 항상 UTF-8에서 작동하고 최대 이식성을 요구하기 위해 당사에서 권장하는 API 집합입니다. -W API는 기존 Windows 코드와의 소스 호환성을 위해 제공됩니다(아마도 전달되는 게임의 기존 Windows PC 버전에서 제공됨).
본체 코드 페이지
UTF-8은 본체에서 기본적이고 유일한 코드 페이지이므로 당사는 그 점을 적극 이용할 수 있도록 -A API를 권장합니다.
Windows PC 코드 페이지
호환성을 위해 Windows PC의 기본 ANSI 코드 페이지는 레거시로 유지됩니다(지역 및 사용자 구성에 따라 다름). 이렇게 하면 Windows PC 및 콘솔을 대상으로 지정한 다음 코드 페이지 변환과 이를 올바르게 수행하는 데 필요한 테스트 매트릭스를 고려해야 하는 경우 부담이 됩니다.
이를 완화하기 위해 Windows에서는 시스템 코드 페이지가 무엇인지에 관계없이 프로세스가 프로세스 코드 페이지로 UTF-8에 옵트인하도록 강제하는 수단을 도입했습니다. 이 점은 패키지 앱에 대해 appxmanifest 또는 ActiveCodePage 속성을 가진 패키지 해제 앱에 대해 퓨전 매니페스트를 사용하여 수행할 수 있습니다. 자세한 내용은 다음 코드 예제를 참조합니다.
참고 항목
이 기능은 Windows 19H1 이상의 빌드에서만 사용할 수 있습니다. 이 속성을 선언하고 이전 Windows 빌드에서 대상으로 지정하거나 실행할 수 있습니다. 그러나 레거지 코드 페이지 검색 및 변환을 지금까지 필요했던 것처럼 처리해야 합니다. 19H1의 최소 대상 버전을 사용하면 프로세스 코드 페이지는 항상 UTF-8입니다.
appxmanifest(packaged)
<?xml version="1.0" encoding="utf-8"?>
<Package xmlns="https://schemas.microsoft.com/appx/manifest/foundation/windows10"
...
xmlns:uap7="https://schemas.microsoft.com/appx/manifest/uap/windows10/7"
xmlns:uap8="https://schemas.microsoft.com/appx/manifest/uap/windows10/8"
...
IgnorableNamespaces="... uap7 uap8 ...">
<Applications>
<Application ...>
<uap7:Properties>
<uap8:ActiveCodePage>UTF-8</uap8:ActiveCodePage>
</uap7:Properties>
</Application>
</Applications>
</Package>
Win32 매니페스트(패키지 해제)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1">
<assemblyIdentity type="win32" name="..." version="6.0.0.0"/>
<application>
<windowsSettings>
<activeCodePage xmlns="https://schemas.microsoft.com/SMI/2019/WindowsSettings">UTF-8</activeCodePage>
</windowsSettings>
</application>
</assembly>
Note: You can add a manifest to an existing executable via the command line with mt.exe -manifest <MANIFEST> -outputresource:<EXE>;#1
MultiByteToWideChar/WideCharToMultiByte
MultiByteToWideChar 및 WideCharToMultiByte 기능을 통해 UTF-8과 UTF-16 (WCHAR)(및 기타 코드 페이지) 간에 변환이 가능합니다. 이것은 레거시 Win32 API가 WCHAR만 식별할 때 특히 유용합니다. 이러한 기능을 통해 UTF-8 입력을 WCHAR로 변환하여 -W API에 전달하고 필요한 경우 다시 어떠한 결과로 변환할 수 있습니다.
Microsoft GDK(게임 개발 키트)에서 이러한 함수를 사용하는 경우 설명서당 0 또는 MB_ERR_INVALID_CHARS의 dwFlags가 포함된 CodePage CP_UTF8을(를) 사용합니다. 그렇지 않으면 ERROR_INVALID_FLAGS 오류가 나타납니다.
참고 항목
콘솔에서 CP_ACP은(는) 항상 CP_UTF8 동일합니다.
CP_UTF8(으)로 명시적으로 전환하는 것이 부담인 경우 기존 코드를 계속 사용할 수 있습니다. Windows PC에서 CP_ACP은(는) 19H1+에서 실행되고 앞에서 설명한 대로 ActiveCodePage 속성이 UTF-8로 설정된 경우에만 CP_UTF8와(과) 같습니다. 그렇지 않은 경우 레거시 시스템 코드 페이지를 따릅니다. 앞으로 이동하는 경우, 가장 좋은 방법은 CP_UTF8을 명시적으로 사용하는 것입니다.
고급 UTF-8에 대한 ICU 및 세계화 지원
ICU는 유니코드 라이브러리에 대한 국제 구성 요소입니다. 이는 C/C++ 인터페이스(예: 정렬, 표준화, 토큰화)로 고급 UTF-8 작업을 지원하는 오픈 소스 및 교차 플랫폼 국제화 라이브러리입니다.
이 라이브러리는 버전 64.1을 기준으로 Microsoft GDK(게임 개발 키트)용으로 업데이트되었습니다. 이 라이브러리를 사용하려면 라이브러리(추가 정보에서 #HowToBuild 참조)를 빌드한 다음 게임을 사용하여 라이브러리를 패키지화합니다(추가 정보에서 #HowToPackage 참조).
참고 항목
추가 정보는 GitHub에서 직접 렌더링되지 않습니다. 리포지토리를 빌드에 로컬로 복제할 경우 로컬로 볼 수 있습니다.
이전 버전의 Windows 지원
19H1(Windows 7 포함) 이전 Windows 빌드를 대상 지정하는 경우 레거시 코드 페이지 검색 및 변환을 처리해야 합니다.
코드 페이지 검색 및 변환을 수행할 필요를 요약하는 Win32 API의 -Utf8 변형을 제공하는 정적 도우미 라이브러리를 제공하고자 노력하고 있습니다. 이는 Windows 7에 이르기까지 콘솔과 Windows PC를 대상으로 하는 공통 프로그래밍 표면을 제공합니다.