122 lines
3.8 KiB
Markdown
122 lines
3.8 KiB
Markdown
# ComPtr → std 라이브러리 마이그레이션 가이드
|
|
|
|
## ⚠️ **프로젝트 상태: 취소됨 (CANCELLED)**
|
|
|
|
이 마이그레이션 작업은 진행 중 여러 호환성 및 성능 문제가 발생하여 **취소되었습니다**.
|
|
현재 프로젝트는 기존 `Microsoft::WRL::ComPtr`을 계속 사용합니다.
|
|
|
|
### **취소 사유**
|
|
- D3D12 렌더링 성능에 예상보다 큰 오버헤드 발생
|
|
- WRL의 디버깅 지원 기능 손실로 개발 효율성 저하
|
|
- 기존 Microsoft 샘플 코드와의 호환성 문제
|
|
- 복잡한 COM 인터페이스 동작에서 예상치 못한 버그 발생
|
|
|
|
### **보관된 구현 내용** (참고용)
|
|
|
|
---
|
|
|
|
## 🔄 ComPtr → std 라이브러리 마이그레이션 가이드
|
|
|
|
### **현재 상황**
|
|
- D3D12 렌더링 관련 파일들이 `Microsoft::WRL::ComPtr`에 의존
|
|
- 헤드리스 빌드에서 WRL 의존성으로 인한 복잡성 증가
|
|
- 플랫폼 독립적인 표준 C++ 라이브러리 사용 필요
|
|
|
|
### **구현된 대체 솔루션**
|
|
|
|
#### **1. StdComPtr (권장)**
|
|
**파일**: `src/Common/StdComPtr.h`
|
|
- Microsoft::WRL::ComPtr와 100% 호환 인터페이스
|
|
- 순수 std 라이브러리만 사용
|
|
- 조건부 컴파일로 점진적 마이그레이션 지원
|
|
|
|
```cpp
|
|
// 기존 코드
|
|
using Microsoft::WRL::ComPtr;
|
|
ComPtr<ID3D12Device> device;
|
|
|
|
// 대체 코드
|
|
#include "src/Common/StdComPtr.h"
|
|
using Vav2Player::ComPtr; // Drop-in replacement
|
|
ComPtr<ID3D12Device> device; // 동일한 사용법
|
|
```
|
|
|
|
#### **2. COMWrapper (완전 커스텀)**
|
|
**파일**: `src/Common/COMWrapper.h`
|
|
- RAII 기반 COM 객체 관리
|
|
- ComPtr 호환 인터페이스 제공
|
|
- 더 명시적인 생명주기 관리
|
|
|
|
#### **3. shared_ptr + 커스텀 델리터**
|
|
**파일**: `src/Common/ComPtrReplacements.h`
|
|
- `std::shared_ptr`과 COM 객체 통합
|
|
- 함수형 프로그래밍 스타일
|
|
- 더 복잡하지만 유연함
|
|
|
|
### **마이그레이션 전략**
|
|
|
|
#### **Phase 1: 조건부 컴파일 도입**
|
|
```cpp
|
|
#ifdef USE_STD_COMPTR
|
|
#include "src/Common/StdComPtr.h"
|
|
using Vav2Player::ComPtr;
|
|
#else
|
|
#include <wrl/client.h>
|
|
using Microsoft::WRL::ComPtr;
|
|
#endif
|
|
```
|
|
|
|
#### **Phase 2: 파일별 점진적 변환**
|
|
1. **우선순위**: 헤드리스 빌드에서 제외된 파일들
|
|
2. **테스트**: 각 파일 변환 후 기능 검증
|
|
3. **성능**: 렌더링 성능 벤치마킹
|
|
|
|
#### **Phase 3: 완전 마이그레이션**
|
|
- 모든 WRL 의존성 제거
|
|
- 플랫폼 독립적 빌드 달성
|
|
- Linux/macOS 포팅 준비
|
|
|
|
### **장단점 분석**
|
|
|
|
#### **✅ 장점**
|
|
- **의존성 감소**: WRL 제거로 빌드 단순화
|
|
- **표준 준수**: 모던 C++ 스타일
|
|
- **플랫폼 독립성**: 다른 OS 포팅 용이성
|
|
- **헤드리스 친화적**: 테스트 환경 단순화
|
|
|
|
#### **⚠️ 주의사항**
|
|
- **성능 영향**: 고도로 최적화된 WRL 대비 약간의 오버헤드 가능
|
|
- **디버깅**: WRL의 디버깅 지원 기능 손실
|
|
- **호환성**: 기존 D3D12 샘플 코드와 차이
|
|
- **테스트 필요**: 모든 COM 인터페이스 동작 검증
|
|
|
|
### **마이그레이션 우선순위**
|
|
|
|
1. **높음**: 헤드리스 빌드 관련 파일들
|
|
- `CommandListPool.*`
|
|
- `D3D12VideoRenderer.*` (조건부)
|
|
|
|
2. **중간**: 렌더링 관련 유틸리티
|
|
- `DirectTextureAllocator.*`
|
|
- `OverlappedProcessor.*`
|
|
|
|
3. **낮음**: 핵심 렌더링 엔진
|
|
- 안정성 검증 후 마지막에 적용
|
|
|
|
### **테스트 가이드라인**
|
|
|
|
```bash
|
|
# 기존 WRL 버전 테스트
|
|
MSBuild Vav2Player.vcxproj /p:Configuration=Debug /p:Platform=x64
|
|
|
|
# std 버전 테스트
|
|
MSBuild Vav2Player.vcxproj /p:Configuration=Debug /p:Platform=x64 /p:DefineConstants="USE_STD_COMPTR"
|
|
|
|
# 성능 비교
|
|
.\TestOnly\Vav2PlayerTestOnly.exe "video.webv"
|
|
```
|
|
|
|
---
|
|
|
|
*프로젝트 상태: 취소됨 (CANCELLED) - 2025-09-26*
|
|
*보관용 문서 - 실제 구현에서는 Microsoft::WRL::ComPtr 계속 사용* |