iOS
Tencent 특수 효과 SDK 핵심 인터페이스 클래스
XMagic.h
는 SDK 초기화, 뷰티 필터 값 업데이트, 애니메이션 호출 등 기능에 사용됩니다.Public 멤버 함수
API | 설명 |
인터페이스 초기화 | |
인터페이스 초기화 | |
뷰티 필터의 다양한 효과 설정 | |
후처리 블러 강도 설정(모든 블러 컴포넌트에 작용) | |
renderSize 설정 | |
리소스 릴리스 인터페이스 | |
데이터 처리 인터페이스 | |
이미지 프로세스 | |
뷰티 필터 매개변수 설정 정보 가져오기 | |
로그 등록 인터페이스 | |
SDK 이벤트 리스너 인터페이스 | |
콜백 정리 인터페이스 등록 | |
현재 GL 컨텍스트 인터페이스 가져오기 | |
SDK 일시 중지 인터페이스 | |
SDK 재개 인터페이스 |
initWithRenderSize
인터페이스 초기화
- (instancetype _Nonnull)initWithRenderSize:(CGSize)renderSizeassetsDict:(NSDictionary* _Nullable)assetsDict;
매개변수
매개변수 | 의미 |
renderSize | 렌더링 크기 |
assetsDict | 리소스 Dict |
initWithGlTexture
인터페이스 초기화
- (instancetype _Nonnull)initWithGlTexture:(unsigned)textureIDwidth:(int)widthheight:(int)heightflipY:(bool)flipYassetsDict:(NSDictionary* _Nullable)assetsDict;
매개변수
매개변수 | 의미 |
textureID | 텍스처 ID |
width | 렌더링 크기 |
height | 렌더링 크기 |
flipY | 이미지 뒤집기 여부 |
assetsDict | 리소스 Dict |
configPropertyWithType
뷰티 필터 효과 구성
- (int)configPropertyWithType:(NSString *_Nonnull)propertyType withName:(NSString *_Nonnull)propertyName withData:(NSString*_Nonnull)propertyValue withExtraInfo:(id _Nullable)extraInfo;
매개변수
매개변수 | 의미 |
propertyType | 효과 유형 |
propertyName | 효과 이름 |
propertyValue | 효과 값 |
extraInfo | 예약 확장, 추가 별도 구성 Dict |
뷰티 필터 효과 설정 예시
뷰티 필터: 미백 효과 설정
NSString *propertyType = @"beauty"; //뷰티 필터 효과 유형 설정, 뷰티 필터 예시NSString *propertyName = @"beauty.whiten"; //뷰티 필터 이름 설정, 미백 예시NSString *propertyValue = @"60"; //미백 효과 값 설정[self.xmagicApi configPropertyWithType:propertyType withName:propertyName withData:propertyValue withExtraInfo:nil];
필터: 설렘 효과 설정
NSString *propertyType = @"lut"; //뷰티 필터 효과 유형 설정, 필터 예시NSString *propertyName = [@"lut.bundle/" stringByAppendingPathComponent:@"xindong_lf.png"]; //뷰티 필터 이름 설정, 설렘 예시NSString *propertyValue = @"60"; //필터 효과 값 설정[self.xmagicApi configPropertyWithType:propertyType withName:propertyName withData:propertyValue withExtraInfo:nil];
몸매 보정: 긴 다리 효과 설정
NSString *propertyType = @"body"; //뷰티 필터 효과 유형 설정, 몸매 보정 예시NSString *propertyName = @"body.legStretch"; //뷰티 필터 이름 설정, 긴 다리 예시NSString *propertyValue = @"60"; //긴 다리 효과 값 설정[self.xmagicApi configPropertyWithType:propertyType withName:propertyName withData:propertyValue withExtraInfo:nil];
애니메이션: 2D 애니메이션으로 귀여운 그래피티 효과 설정
NSString *motion2dResPath = [[NSBundle mainBundle] pathForResource:@"2dMotionRes" ofType:@"bundle"];//2dMotionRes 폴더의 절대 경로NSString *propertyType = @"motion"; //뷰티 필터 효과 유형 설정, 애니메이션 효과 예시NSString *propertyName = @"video_keaituya"; //뷰티 필터 이름 설정, 2D 애니메이션으로 귀여운 그래피티 효과 예시NSString *propertyValue = motion2dResPath; //애니메이션 효과 경로 설정[self.xmagicApi configPropertyWithType:propertyType withName:propertyName withData:propertyValue withExtraInfo:nil];
메이크업: 걸그룹 메이크업 효과 설정
NSString *motionMakeupResPath = [[NSBundle mainBundle] pathForResource:@"makeupMotionRes" ofType:@"bundle"];//makeMotionRes 폴더의 절대 경로NSString *propertyType = @"motion"; //뷰티 필터 효과 유형 설정, 메이크업 예시NSString *propertyName = @"video_nvtuanzhuang"; //뷰티 필터 이름 설정, 걸그룹 메이크업 예시NSString *propertyValue = motionMakeupResPath; //애니메이션 효과 경로 설정[self.xmagicApi configPropertyWithType:propertyType withName:propertyName withData:propertyValue withExtraInfo:nil];//아래는 메이크업 값 설정(위의 애니메이션 효과는 한 번만 호출하면 되며, 아래의 메이크업 값 설정은 여러 번 호출 가능)NSString *propertyTypeMakeup = @"custom"; //뷰티 필터 효과 유형 설정, 메이크업 예시NSString *propertyNameMakeup = @"makeup.strength"; //뷰티 필터 이름 설정, 걸그룹 메이크업 예시NSString *propertyValueMakeup = @"60"; //메이크업 효과값 설정[self.xmagicApi configPropertyWithType:propertyTypeMakeup withName:propertyNameMakeup withData:propertyValueMakeup withExtraInfo:nil];
분할: 배경 블러 처리 설정(강한 효과)
NSString *motionSegResPath = [[NSBundle mainBundle] pathForResource:@"segmentMotionRes" ofType:@"bundle"];//segmentMotionRes 폴더의 절대 경로NSString *propertyType = @"motion"; //뷰티 필터 효과 유형 설정, 분할 예시NSString *propertyName = @"video_segmentation_blur_75"; //뷰티 필터 이름 설정, 배경 블러 처리-강함 예시NSString *propertyValue = motionSegResPath; //애니메이션 효과 경로 설정NSDictionary *dic = @{@"bgName":@"BgSegmentation.bg.png", @"bgType":@0, @"timeOffset": @0},@"icon":@"segmentation.linjian.png"};//예약 필드 설정[self.xmagicApi configPropertyWithType:propertyType withName:propertyName withData:propertyValue withExtraInfo:dic];
사용자 정의 배경:
NSString *motionSegResPath = [[NSBundle mainBundle] pathForResource:@"segmentMotionRes" ofType:@"bundle"];//segmentMotionRes 폴더의 절대 경로NSString *propertyType = @"motion"; //뷰티 필터 효과 유형 설정, 분할 예시NSString *propertyName = @"video_empty_segmentation"; //뷰티 필터 이름 설정, 사용자 정의 배경 예시NSString *propertyValue = motionSegResPath; //애니메이션 효과 경로 설정NSString *imagePath = @"/var/mobile/Containers/Data/Application/06B00BBC-9060-450F-8D3A-F6028D185682/Documents/MediaFile/image.png"; //사용자 정의 배경 이미지의 절대 경로입니다. 사용자 정의 배경으로 비디오를 선택한 경우 비디오를 압축 및 트랜스 코딩해야 하며 압축 및 트랜스 코딩 후의 절대 경로 사용int bgType = 0;//사용자 정의 배경 유형입니다. 0이미지, 1비디오int timeOffset = 0;//지속 시간. 이미지 배경일 때 0; 비디오 배경 시 비디오 지속 시간NSDictionary *dic = @{@"bgName":imagePath, @"bgType":@(bgType), @"timeOffset": @(timeOffset)},@"icon":@"segmentation.linjian.png"};//예약 필드 설정[self.xmagicApi configPropertyWithType:propertyType withName:propertyName withData:propertyValue withExtraInfo:dic];
emitBlurStrengthEvent
후처리 블러 강도 설정(모든 블러 컴포넌트에 작용)
- (void)emitBlurStrengthEvent:(int)strength;
매개변수
매개변수 | 의미 |
strength | 효과 값 |
setRenderSize
renderSize 설정
- (void)setRenderSize:(CGSize)size;
매개변수
매개변수 | 의미 |
size | 렌더링 크기 |
deinit
리소스 릴리스 인터페이스
- (void)deinit;
process
데이터 인터페이스 처리
- (YTProcessOutput* _Nonnull)process:(YTProcessInput * _Nonnull)input;
매개변수
매개변수 | 의미 |
input | 처리 데이터 정보 입력 |
processUIImage
이미지 처리
- (UIImage* _Nullable)processUIImage:(UIImage* _Nonnull)inputImage needReset:(bool)needReset;
매개변수
매개변수 | 의미 |
inputImage | 입력 이미지의 권장되는 최대 크기는 2160×4096입니다. 이 크기보다 큰 사진은 얼굴 인식 결과가 좋지 않거나 얼굴을 인식할 수 없으며 OOM 문제가 발생할 수 있음 |
needReset | 다음 시나리오에서는 needReset을 true로 설정해야 합니다: 이미지 전환 처음으로 분할 사용 처음으로 애니메이션 사용 처음으로 메이크업 사용 |
getConfigPropertyWithName
뷰티 필터 매개변수 설정 정보 가져오기
- (YTBeautyPropertyInfo * _Nullable)getConfigPropertyWithName:(NSString *_Nonnull)propertyName;
매개변수
매개변수 | 의미 |
propertyName | 이름 설정 |
registerLoggerListener
로그 등록 인터페이스
- (void)registerLoggerListener:(id<YTSDKLogListener> _Nullable)listener withDefaultLevel:(YtSDKLoggerLevel)level;
매개변수
매개변수 | 의미 |
listener | 로그 콜백 인터페이스 |
level | 로그 출력 level, 기본 ERROR |
registerSDKEventListener
SDK 이벤트 리스너 인터페이스
- (void)registerSDKEventListener:(id<YTSDKEventListener> _Nullable)listener;
매개변수
매개변수 | 의미 |
listener | 이벤트 리스너 콜백, 주로 AI 이벤트, Tips 프롬프트 이벤트, Asset 이벤트로 구분 |
clearListeners
콜백 정리 인터페이스 등록
- (void)clearListeners;
getCurrentGlContext
현재 GL 컨텍스트 인터페이스 가져오기
- (nullable EAGLContext*)getCurrentGlContext;
onPause
SDK 일시 중지 인터페이스
/// @brief APP는 일시 중지 시 SDK 일시 중지 인터페이스 호출- (void)onPause;
onResume
SDK 복구 인터페이스
/// @brief APP는 복구 시 SDK 복구 인터페이스 호출- (void)onResume;
정적 함수
API | 설명 |
뷰티 필터 매개변수의 인증 정보 가져오기 |
isBeautyAuthorized
뷰티 필터 매개변수의 인증 정보 가져오기(뷰티 필터와 몸매 보정만 지원)
/// @param featureId 뷰티 필터 매개변수 설정/// @return 해당 뷰티 필터 매개변수의 인증 결과 반환+ (BOOL)isBeautyAuthorized:(NSString * _Nullable)featureId;
콜백
API | 설명 |
SDK 내부 이벤트 콜백 인터페이스 | |
로그 리스너 콜백 |
YTSDKEventListener
SDK 내부 이벤트 콜백 인터페이스
@protocol YTSDKEventListener <NSObject>
멤버 함수
반환 유형 | 이름 |
void | |
void | |
void | |
void |
함수 설명
onYTDataEvent
YTDataUpdate 이벤트 콜백
/// @param event NSString*형식의 콜백- (void)onYTDataEvent:(id _Nonnull)event;
JSON string 구조를 반환하고 최대 5개의 안면 인식 정보 반환:
{"face_info":[{"trace_id":5,"face_256_point":[180.0,112.2,...],"face_256_visible":[0.85,...],"out_of_screen":true,"left_eye_high_vis_ratio:1.0,"right_eye_high_vis_ratio":1.0,"left_eyebrow_high_vis_ratio":1.0,"right_eyebrow_high_vis_ratio":1.0,"mouth_high_vis_ratio":1.0},...]}
필드 의미
필드 | 유형 | 값범위 | 설명 |
trace_id | int | [1,INF) | 안면 인식 ID. 연속 스트리밍 과정에서 동일한 ID를 가진 사람들을 동일한 얼굴로 간주할 수 있음 |
face_256_point | float | [0,screenWidth] 또는 [0,screenHeight] | 총 512개의 숫자, 256개의 안면 인식 키 포인트가 있으며 화면의 왼쪽 상단 모서리는 (0,0) |
face_256_visible | float | [0,1] | 안면 인식 256 키 포인트 가시도 |
out_of_screen | bool | true/false | 얼굴이 프레임 밖에 있는지 여부 |
left_eye_high_vis_ratio | float | [0,1] | 왼쪽 눈 높이 가시성 포인트의 비율 |
right_eye_high_vis_ratio | float | [0,1] | 오른쪽 눈 높이 가시성 포인트의 비율 |
left_eyebrow_high_vis_ratio | float | [0,1] | 왼쪽 눈썹 높이 가시성 포인트의 비율 |
right_eyebrow_high_vis_ratio | float | [0,1] | 오른쪽 눈썹 높이 가시성 포인트의 비율 |
mouth_high_vis_ratio | float | [0,1] | 입 높이 가시성 포인트의 비율 |
onAIEvent
AI 이벤트 콜백
/// @param event dict 형식의 콜백- (void)onAIEvent:(id _Nonnull)event;
onTipsEvent
프롬프트 이벤트 콜백
/// @param event dict 형식의 콜백- (void)onTipsEvent:(id _Nonnull)event;
onAssetEvent
리소스 패키지 이벤트 콜백
/// @param event string 형식의 콜백- (void)onAssetEvent:(id _Nonnull)event;
YTSDKLogListener
로그 리스너 콜백
@protocol YTSDKLogListener <NSObject>
멤버 함수
반환 유형 | 함수 이름 |
void | onLog |
함수 설명
onLog
로그 리스너 콜백
/// @param loggerLevel 현재 로그 수준 반환/// @param logInfo 현재 로그 정보 반환- (void)onLog:(YtSDKLoggerLevel) loggerLevel withInfo:(NSString * _Nonnull) logInfo;