Android 멀티 뷰

언리얼 엔진용 Android 구성하기

Android 단일 인스턴스 서비스(Android Single Instance Service, ASIS)를 성공적으로 패키징하려면 Android SDK와 NDK를 구성해야 합니다. 언리얼 엔진(UE)에서는 Android Studio 및 Android SDK 명령줄 툴을 사용하여 Android 프로젝트 개발에 필요한 Android SDK 컴포넌트를 다운로드하고 설치합니다. 다음 문서를 따라 진행하세요.

언리얼 엔진 5.5.x 사용자라면 다음 SDK 플랫폼 및 툴을 활성화합니다.

템플릿에서 프로젝트 생성하기

Android SDK/NDK가 설치되면 이제 ASIS 템플릿 플러그인을 구성할 수 있습니다. 플러그인은 별도의 아카이브로 제공되므로 UE 소스 코드를 준비하려면 수동으로 단계를 진행해야 합니다.

UE5.* 소스 코드 얻기

Perforce 또는 Github의 UE5 메인(Main)에서 최신 소스 코드를 가져옵니다.

퍼포스(Perforce):

• Perforce를 통해 언리얼 엔진 액세스하기

Github:

• GitHub에서 언리얼 엔진 소스 코드 다운로드하기

ASIS 플러그인 구성하기

Perforce 사용 시:

1. ASIS 플러그인 폴더(UE5_Main\Engine\Restricted\NotForLicensees\Plugins\AndroidSingleInstanceService)로 이동합니다.

2.  AndroidSingleInstanceService 폴더 내에서 Templates 폴더(UE5_Main/Engine\Restricted\NotForLicensees\Plugins\AndroidSingleInstanceService\Templates\)를 엽니다.

Github 사용 시:

에픽에서 제공한 아카이브의 압축을 해제하고 ASIS 플러그인 콘텐츠를 다음 위치에 복사합니다. Engine\Restricted\NotForLicensees\Plugins\AndroidSingleInstanceService

템플릿 복사하기

TP_HMI_ASIS 폴더를 UE5/Templates/에 복사합니다.

그리고 나서 다음 코드를 UE5_Main/Templates/TemplateCategories.ini에 복사합니다.

Categories=(Key="HMI", LocalizedDisplayNames=((Language="en",Text="Automotive\nHMI &\nVehicle Cockpit using Android Single Instance Service")), LocalizedDescriptions=((Language="en",Text="Find templates for automotive vehicle cockpit using Android Single Instance Service"), Icon="TP_HMI_ASIS/Media/AutomotiveHMI_2x.png", IsMajorCategory=true)

UnrealEditor를 실행합니다. 이제 언리얼 엔진 프로젝트 브라우저를 열면 새 HMI 템플릿이 보일 것입니다.

HMI 템플릿에서 프로젝트 생성하기

프로젝트는 다음과 같은 모습일 것입니다.

기존 프로젝트에 ASIS 플러그인 추가하기

ASIS를 추가해야 하는 기존 프로젝트가 있는 경우, 다음과 같이 진행합니다.

1. 플러그인 세팅에서 ASIS 활성화하기

   

2. 리매핑 플러그인 디렉터리를 추가합니다. 다음 코드를 {ProjectName}/Config/DefaultGame.ini에 추가합니다.

   C++

   [Staging]
   +RemapDirectories=(From="Engine/Restricted/NotForLicensees/Plugins/AndroidSingleInstanceService", To="Engine/Plugins/Runtime/AndroidSingleInstanceService")
   +RemapDirectories=(From="Engine/Restricted/NotForLicensees/Plugins/Experimental/MultiWindow", To="Engine/Plugins/Experimental/MultiWindow")
   

   Copy full snippet(3 lines long)

3. 프로젝트를 열고 다음 ASIS 플러그인 세팅을 활성화합니다.

   

ASIS 예시 패키징 및 실행하기

언리얼 엔진에서 Android SDK/NDK와 템플릿을 구성했다면, 이제 프로젝트를 Android 애플리케이션으로 패키징할 수 있습니다.

앱 통신

언리얼 엔진에서 앱이 패키징되면, 예시 클라이언트 앱을 사용하여 언리얼 엔진 APK와 통신해 보겠습니다.

언리얼 엔진 패키지에는 3개의 아티팩트가 있습니다.

1. Android 서비스가 포함된 APK. 이는 프로젝트 패키지 대화창에서 선택한 폴더에 있습니다.

2. 클라이언트 애플리케이션에서 사용되는 ASIS 헬퍼 라이브러리.

   C++

   Binaries/Android/aars
   ├── asisclientlib-1.0.1-debug.aar
   ├── asisclientlib-1.0.1-debug.jar
   ├── asiscommon-1.0.1-debug.aar

   Copy full snippet(4 lines long)

3. 서비스와 통신하는 예시 클라이언트 애플리케이션. 이는 패키지로 만든 언리얼 엔진 프로젝트가 아니라 언리얼 엔진 프로젝트의 Binaries 폴더에 있습니다. 위치는 \Unreal Projects\*Project_Name*\Binaries\Android입니다.

   

Android Studio를 사용하여 Android 프로젝트를 열 수 있습니다. 이 프로젝트를 열면 자동으로 Android 빌드 프로세스를 진행합니다.

아니면 명령줄을 사용할 수도 있습니다.

cmd를 사용하여 클라이언트 APK를 생성할 수 있습니다.

cd {Project_Name}\Binaries\Android\ExampleUseCase_{Project_Name}\
gradlew assembleDebug

다음 위치에 APK가 생성됩니다. {Project_Name}\Binaries\Android\ExampleUseCase_{Project_Name}\app\build\outputs\apk\debug\app-debug.apk

Android Studio로 돌아와서 Android 디바이스를 선택한 상태로 Shift+F10을 누르거나 상단 메뉴에서 녹색 Play 버튼을 선택하여 앱을 실행할 수 있습니다.

설치 후 서비스 

이제 디바이스에 언리얼 엔진 APK 설치를 실행하여 애플리케이션을 실행합니다. 언리얼 엔진 패키지 폴더에서 명령줄을 사용하여 adb를 실행할 수 있습니다.

Android 앱에서 Activate View1, View2 및 View3을 선택하여 언리얼 엔진 애플리케이션과 통신하는 Android 서비스를 확인합니다.

멀티 뷰 활성화하기

멀티 뷰는 UE 5.6 버전부터 지원됩니다. 멀티 뷰를 활성화하려면 AndroidSingleInstanceService 플러그인이 필요합니다. 이전 단계를 수행하여 ASIS를 활성화하면, 여기에서 시작할 수 있습니다.

플러그인 세팅에서 Multiview 플러그인을 활성화합니다.

레벨에 멀티 뷰를 테스트할 두 개의 카메라를 생성합니다. 이 예시에서는 TP_HMI_Automotive를 사용합니다.

다음으로 레벨 블루프린트를 엽니다. 블루프린트에 카메라 액터(Camera Actor)를 추가합니다. Camera Actor 노드를 드래그하고 'Get Camera View'를 선택합니다. 그런 다음, Get Camera 노드를 삭제합니다. 카메라 컴포넌트 오브젝트 레퍼런스(Camera Component Object Reference)만 필요하기 때문입니다.

그런 다음, Register Camera for Asis를 생성합니다. 카메라 오브젝트 노드를 해당 노드에 연결합니다. 각 카메라에 대해 카메라 ID(Camera ID)를 1과 2로 설정해야 합니다. 실행 핀을 Event Begin Play에 연결합니다.

Android용 프로젝트를 패키징합니다.

이제 Android Studio에서 클라이언트 앱을 엽니다. 예시 클라이언트 Android 애플리케이션 프로젝트를 엽니다. 이는 패키지로 만든 언리얼 엔진 프로젝트가 아니라 언리얼 엔진 프로젝트의 Binaries 폴더에 있습니다. 클라이언트 앱용 소스 코드의 위치는 다음과 같습니다. {Project_Name}\Binaries\Android\ExampleUseCase_{Project_Name}\

그런 다음, 표준 ASIS에서 MultiviewEdit으로 전환합니다.

Binaries\Android\ExampleUseCase_{Project_Name}\app\src\main\AndroidManifest.xml을 편집하여 22번째 줄의 게임 액티비티를 ActivityForMultiView로 변경합니다.

Android Studio에서 Android 디바이스를 연결한 상태로 Shift+F10을 누르거나 상단 메뉴에서 녹색 Play 버튼을 클릭하여 앱을 실행할 수 있습니다.

설치 후 서비스 

이제 디바이스에 언리얼 엔진 APK 설치를 실행하여 애플리케이션을 실행합니다. 언리얼 엔진 패키지 폴더에서 명령줄을 사용하여 adb를 실행할 수 있습니다.

Attach/Detach View1 및 Attach/Detach View2를 선택하여 카메라를 확인합니다. 이제 Android에서 멀티 뷰가 작동하는 ASIS를 사용할 수 있습니다.

아키텍처 개요

지원되는 접근 방식

인터페이스 설명

클래스 ASISConnection

이 클래스를 사용하면 연결을 설정하고 ASIS 서비스와 통신할 수 있습니다. 이 통신의 복잡성을 캡슐화하여 데이터와 명령을 전송하고 수신하는 사용하기 쉬운 인터페이스를 제공합니다.

ASISConnection.ASISConnectionCallBacks 인터페이스는 ASISConnection 이벤트에 대한 콜백을 정의합니다. 연결 성공 이벤트를 처리하려는 경우 이 인터페이스를 구현하세요.

public interface ASISConnectionCallBacks
{
void onConnectionSuccess();
void onServiceDisconnected();
}

onConnectionSuccess() - 서비스에 대한 연결이 성공적으로 설정되었을 때 호출됩니다.

onServiceDisconnected() - 서비스에 대한 연결이 끊어졌을 때 호출됩니다.

ASISConnection.EngineMessagesListener 인터페이스는 엔진 메시지에 대한 리스너를 정의합니다.  엔진의 메시지를 처리하려는 경우 이 인터페이스를 구현하세요.

public interface EngineMessagesListener
{
void onEngineMessage(Message message);
}

onEngineMessage(Message message) - 엔진에서 메시지를 수신했을 때 호출됩니다.

Message - 수신하는 메시지의 값입니다.

클래스 ASISConnection.ConnectionBuilder 

이 클래스는 빌더 디자인 패턴을 구현하여 ASISConnection의 인스턴스를 생성합니다. 메서드를 체인으로 연결할 있는 플루언트 스타일을 따르기 때문에 여러 파라미터가 필요할 때 가독성을 높일 수 있습니다.

ConnectionBuilder(Context ctx)

주어진 컨텍스트를 사용하여 `ConnectionBuilder` 클래스의 새 인스턴스를 초기화합니다. 

파라미터

• ctx - ConnectionBuilder를 생성할 컨텍스트입니다.

public ConnectionBuilder withConnectionListener(ASISConnectionCallBacks connectionListener)

ASISConnection에 대한 ASISConnectionCallBacks 리스너를 설정합니다.

파라미터

• connectionListener - 설정할 ASISConnectionCallBacks 리스너입니다.

반환

• 메서드 체인 연결을 허용하는 ConnectionBuilder 인스턴스입니다.

public ConnectionBuilder withEngineMessageListener(EngineMessagesListener engineMessageListener)

ASISConnection에 대한 EngineMessagesListener를 설정합니다.

파라미터

• engineMessageListener - 설정할 EngineMessagesListener 리스너입니다.

반환

• 메서드 체인 연결을 허용하는 ConnectionBuilder 인스턴스입니다.

public ConnectionBuilder withConnectionId(String connectionID)

ASISConnection에 대한 connectionID를 설정합니다.

파라미터

• connectionID - connectioID가 포함된 스트링입니다.

반환

• 메서드 체인 연결을 허용하는 ConnectionBuilder 인스턴스입니다.

public ConnectionBuilder withServicePackageName(String packageName)

디폴트 서비스 패키지 이름을 오버라이드합니다.

파라미터

• packageName - 서비스 패키지 이름(com.epicgames.PROJECTNAME)입니다.

반환

• 메서드 체인 연결을 허용하는 ConnectionBuilder 인스턴스입니다.

public ConnectionBuilder withServiceClassName(String className)

디폴트 서비스 클래스 이름을 오버라이드합니다.

파라미터

1. className - 서비스 클래스 이름(com.epicgames.makeaar.UnrealSharedInstanceService)입니다.

반환

• 메서드 체인 연결을 허용하는 ConnectionBuilder 인스턴스입니다.

public ConnectionBuilder withObbModuleName(String obbModuleName)

디폴트 obbModuleName을 오버라이드합니다.

파라미터

• obbModuleName - 콘텐츠 obb 이름(UE 프로젝트 이름)입니다.

반환

• 메서드 체인 연결을 허용하는 ConnectionBuilder 인스턴스입니다.

public ConnectionBuilder withInsightsTracing()

InsightsTracing을 활성화합니다.

반환

• 메서드 체인 연결을 허용하는 ConnectionBuilder 인스턴스입니다.

public ConnectionBuilder withCommandLineArgs(String cmdArgs)

디폴트 명령줄 실행인자를 오버라이드합니다.

파라미터

1. cmdArgs - UE 시작을 위한 명령줄 실행인자입니다.

반환

• 메서드 체인 연결을 허용하는 ConnectionBuilder 인스턴스입니다.

public ConnectionBuilder withOverridePropagateAlpha(boolean value)

디폴트 모바일 전파 알파 값을 오버라이드합니다.

파라미터

• value - 모바일 전파 알파 값을 오버라이드합니다.

반환

• 메서드 체인 연결을 허용하는 ConnectionBuilder 인스턴스입니다.

public ASISConnection build()

설정된 파라미터를 사용하여 ASISConnection 인스턴스를 빌드합니다.

반환

• 새 ASISConnection 인스턴스입니다.

예시:

public class UseServiceActivity extends Activity
     implements ASISConnection.ASISConnectionCallBacks,
   ASISConnection.EngineMessagesListener
....
ASISConnection mServiceConnection ;
...

mServiceConnection = new ASISConnection.ConnectionBuilder(this)					.withServicePackageName("com.epicgames.UE_PROJECT")
		.withObbModuleName("UE_PROJECT")
		.withConnectionListener(this)

ASISConnection(ConnectionBuilder builder)

ConnectionBuilder를 argument.ConnectionBuilder로 받는 생성자입니다.

이 생성자는 일반적으로 ConnectionBuilder의 build() 메서드를 통해 사용됩니다.

public boolean bindToUnrealInstanceService()

주어진 호출자에 의해 언리얼 Android 단일 인스턴스 서비스에 바인딩합니다.

반환

• 바인딩이 성공하면 true, 그렇지 않으면 false입니다.

public void unbindToUnrealInstanceService()

언리얼 인스턴스 서비스에서 바인딩을 해제합니다.

public boolean isBoundToService()

애플리케이션이 현재 서비스에 바인딩되어 있는지 확인합니다.

반환

• 이 메서드는 애플리케이션이 서비스에 바인딩된 경우 true를 반환합니다.

public int attachSurfaceToService(int displayIndex, Surface externalSurface)

렌더링을 위해 서비스에 외부 표면을 어태치합니다.

파라미터:

• displayIndex: 디스플레이의 인덱스입니다. 단일 디스플레이이면 0입니다.

• externalSurface: 어태치할 표면입니다.

반환:

• 어태치된 표면의 ID입니다.

public boolean detachSurfaceFromService(int attachId, Handler.Callback callback)

ID를 어태치하여 서비스에서 표면을 디태치합니다.

파라미터:

• attachId: 표면을 디태치할 어태치먼트 ID입니다.

• callback: 디태치가 완료되면 호출되는 콜백입니다.

반환

• 디태치가 성공적으로 시작되면 true이고, 그렇지 않으면 false입니다.

public boolean sendData(String key, Object value)

이 메서드를 사용하면 키-값 데이터를 ASIS 서비스에 전송할 수 있습니다.

파라미터

• key: 전송되는 데이터의 키를 나타내는 스트링입니다.

• value: 전송할 데이터 조각입니다.

반환

• 이 메서드는 데이터가 성공적으로 전송되었는지 여부를 나타내는 부울을 반환합니다.

public boolean consoleCommand(String consoleCommand)

연결된 서비스에 콘솔 명령을 전송합니다.

파라미터

• consoleCommand: 콘솔 명령이 포함된 스트링입니다.

반환

• 메시지를 성공적으로 전송하면 true를 반환합니다.

public boolean sendTouchEvent(MotionEvent event, int attachId)

어태치된 표면에서 서비스로 터치 이벤트를 포워딩합니다.

파라미터

• event: 터치 이벤트를 나타내는 Android 모션 이벤트입니다.

• attachId: 표면과 연결된 ID입니다.

반환

• 터치 이벤트를 성공적으로 전송하면 true를 반환하고, 그렇지 않으면 false를 반환합니다.

Android 애플리케이션 통합

프로젝트에 ASIS Java 라이브러리를 임포트합니다. 

• 생성된 라이브러리를 {Project_Name}\Binaries\Android\aars에서 내 앱 공간(예: libs)으로 복사합니다.

{Android_app}/libs
├── asisclientlib-1.0.1-debug.aar
├── asisclientlib-1.0.1-debug.jar
├── asiscommon-1.0.1-debug.aar
└── asiscommon-1.0.1-debug.jar

• build.gradle을 통해 라이브러리에 임포트를 추가합니다.

android {
 	...
	repositories {
		flatDir { dirs 'libs' }
	}
...
}

def asiscommonVersion = "1.0.1"
def asisclientlibVersion = "1.0.1"

애플리케이션 활동 수명 주기 시퀀스 다이어그램: